Open Stack

On 2015-07-01 11:33:02 +0300 (+0300), Olga Gusarenko wrote:
[...]
> *Documentation Contributor Guide: to be or not to be? *
> 
> 2. Where is the most appropriate location for it?
> 
> I agree that http://docs.openstack.org/infra is the best place, but before
> taking any steps in this direction, we should thoroughly discuss what kind
> of content this should include with the its owner, and find a compromise.
> Jeremy, did I understand your point right?
[...]

Yes, basically we moved most of the general contributor workflow
documentation out of the wiki already and into its own Git repo.
This was partly for ease of maintenance, but mostly because putting
it under direct oversight of the admins who maintain that
infrastructure avoids the earlier situation we had where the wiki
started accumulating bad advice, misinformation and was generally
out of touch with the reality of our systems. Keeping on top of the
various and sundry wiki articles which partly duplicated one another
and got continually updated to include everyone's pet tips and
preferences led to an unreadable mess and was a liability to our
entire contributor base.

We reused what we could, corrected what we should, and reorganized
it all into chapters based on clearly-delineated role audiences
(developer, core reviewer, project driver). Since then a few
specialist guides and "how to" walkthroughs have been added (new
repository creation, Python-specific developer recommendations, a
sandbox-based new contributor tutorial) which could stand to be
moved or reorganized a bit for better flow. So there's a fuzzy line
between what's general enough to go in the main three chapters and
what's specific to certain subgroups of contributors or uncommon
tasks but still a fit as a separate chapter.

It sounds like some of what you're discussing could simply be
improvements to the "Getting Started" section of the "Developer's
Guide." We use the term "developer" loosely to mean anyone
submitting patches to our code review system, so its intent is to be
applicable to documentation contributors too and not just software
developers specifically.
-- 
Jeremy Stanley