[openstack-dev] [all] creating a unified developer reference manual

Stefano Maffulli stefano at openstack.org
Thu Feb 26 22:14:01 UTC 2015


On Wed, 2015-02-25 at 14:54 -0500, Doug Hellmann wrote:
> 1. Should we have a unified developer guide for the project?

Yes. Absolutely. Yes.

> 2. Where should it live and how should we manage it?

I think the natural destination for it would be the URL
http://docs.openstack.org/developer (which should be instead
named /contributor to avoid collision with developer.openstack.org)

I started playing around with an entry portal for new contributors, one
that would give a clear path (think a ladder) from setup dev environment
to first code reviews to full on core member. Since we teach this stuff
at Upstream Training, I used the timeline in the class to start
assembling a table of content for a new contributor's guide

https://etherpad.openstack.org/p/coherent-path-for-contributors

> I believe we would benefit by having a more formal place to write down
> some of our experiences in ways that make them discoverable. We have
> been using the wiki for this, but it is often challenging to find
> information in the wiki if you don’t generally know where to look for
> it. 

The problem is that some stuff is in the wiki (which can be and is being
improved, btw) and some other stuff is scattered around and often
duplicated in project's repos. 

> That leads to an answer to question 2: create a new git repository to
> host a Sphinx-based manual similar to what many projects already have.
> We would then try to unify content from all sources where it applies
> to the whole project, and we could eventually start moving some of the
> wiki content into it as well.

This sounds like a good approach to me already. Unless someone has
better alternatives, I'd go for it.

> If we decide to create the repository, we would also need to decide
> how it would be managed. The rules set up for the cross-project specs
> repository seems close to what we want (everyone can +1/-1; TC members
> can +2/-2; the TC chair tallies the votes and uses workflow+1) [4].

Sounds good to me, at least to get started. At some point the people who
care the most for this effort will emerge and maybe the TC will give the
+w also to them.

/stef




More information about the OpenStack-dev mailing list