[Gluster-devel] [Cross-posted] Re: Gentle Reminder.. (Was: GlusterFS Documentation Improvements - An Update)

[Jeff Darcy]

> 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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.gluster.org/pipermail/gluster-devel/attachments/20150708/6d381123/attachment-0001.html>