> 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@gluster.org http://www.gluster.org/mailman/listinfo/gluster-devel
