My suggestions:
- Differentiate between user doc(installation, administration, feature summary, tools, FAQ/troubleshooting etc) and developer doc(Design doc, developer workflow, coding guidelines etc).
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.
- User documentation goes to glusterdocs repo and developer documentation stays in gluster repo.
- 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.
- 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.
- A patch which changes a struct member should change the relevant developer documentation in the same patch set.
- 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).
- Use github's PR for glusterfsdocs and hence use the comments system on github for that.
- 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.
_______________________________________________ Gluster-devel mailing list Gluster-devel@xxxxxxxxxxx http://www.gluster.org/mailman/listinfo/gluster-devel
