<html><body><div style="font-family: times new roman, new york, times, serif; font-size: 12pt; color: #000000"><div><br>
</div><blockquote style="border-left:2px solid #1010FF;margin-left:5px;padding-left:5px;color:#000;font-weight:normal;font-style:normal;text-decoration:none;font-family:Helvetica,Arial,sans-serif;font-size:12pt;"><b>My suggestions:</b><div style="color: rgb(34, 34, 34); font-family: arial, sans-serif;
font-size: small; font-style: normal; font-variant: normal;
font-weight: normal; letter-spacing: normal; line-height: normal;
orphans: auto; text-align: start; text-indent: 0px;
text-transform: none; white-space: normal; widows: 1;
word-spacing: 0px; -webkit-text-stroke-width: 0px;
background-color: rgb(255, 255, 255);"><ul><li>Differentiate between user doc(installation, administration,
feature summary, tools, FAQ/troubleshooting etc) and developer
doc(Design doc, developer workflow, coding guidelines etc).</li></ul></div></blockquote><div><br></div><div>I think there's a third category: feature/release planning and tracking. That stuff doesn't belong in the online equivalent of a manual, though it should be linked from there. It also doesn't belong in the same git repository with code, because it's explicitly not associated with a particular version of code. However, putting it in a *separate* git repository might work. Having history would be nice. Gerrit and github both provides reasonable inline-commenting facilities to support the kinds of discussions that need to occur, plus a way to finalize the results of those discussions with a commit. My main concern is that such a setup might seem inaccessible to users who aren't familiar with those developer-oriented workflows. For them, probably nothing more cumbersome than a wiki would be sufficient. On the other hand, I have yet to see such a user edit one of our feature/planning pages even when those were in a wiki. I can barely get my fellow developers to do so, even when the features are their own, so maybe usability just isn't the issue.<br></div><blockquote style="border-left:2px solid #1010FF;margin-left:5px;padding-left:5px;color:#000;font-weight:normal;font-style:normal;text-decoration:none;font-family:Helvetica,Arial,sans-serif;font-size:12pt;"><div style="color: rgb(34, 34, 34); font-family: arial, sans-serif;
font-size: small; font-style: normal; font-variant: normal;
font-weight: normal; letter-spacing: normal; line-height: normal;
orphans: auto; text-align: start; text-indent: 0px;
text-transform: none; white-space: normal; widows: 1;
word-spacing: 0px; -webkit-text-stroke-width: 0px;
background-color: rgb(255, 255, 255);"><ul><li>User documentation goes to glusterdocs repo and developer
documentation stays in gluster repo.<br></li><li>An user/admin who installed through packages can do a
man(and find man pages) or google(and find readthedocs pages)
without going through gerrit/wiki etc.<br></li><li>A developer who has cloned gluster repo finds all the
development related info in the repo itself(git grep etc) and
does not need to go out of the code base.<br></li><li>A patch which changes a struct member should change the
relevant developer documentation in the same patch set.<br></li><li>A patch which changes a user facing behavior should be
ideally followed by a PR on glusterdocs repo. (patch owner and
feature maintainer to ensure that).</li><li>Use github's PR for glusterfsdocs and hence use the comments
system on github for that.</li><li>A developer doc change or a new feature proposal should be
as patch on gluster repo and we can use gerrit's inline
comments for discussion on that.</li></ul></div></blockquote><div><br></div></div></body></html>