Open Stack

On Wed, Mar 23 2016, Mike Perez wrote:

> As seen from the Manila review [1], the install docs team is suggesting these
> to be put in their developer guide.
>
> I don't think this is a great idea. Mainly because they are for developers,
> operators aren't going to be looking in there for install information. Also the
> Developer doc page [4] even states "This page contains documentation for Python
> developers, who work on OpenStack itself".
>
> The install docs team doesn't want to be swamped with everyone in big tent
> giving them their install docs, to be verified, and eventually likely to be
> maintained by the install docs team.

So what I've been pushing for a few years now (and I keep trying) is to
have the user documentation be required as part of the code that is
contributed by the project – just like we did for unit tests, and just
like we finally do with functional tests (e.g. tempest-lib).

We did that for day 1 with Gnocchi, and so far it works pretty far:

  http://gnocchi.xyz/install.html

The project is probably (made) less complex than e.g. Neutron or Manila
to deploy, but it should be possible to achieve some of that for most
projects. Actually, believe it or not, many open-source projects out
there also do that with great success.

That doc-is-mandatory-with-your-code policy does not prevent the doc
team to do its job. But it makes sure that the people writing the doc
are the same that wrote the code, which brings a few interesting side
effects:

- you can spot mistakes in the code or the doc just by seeing the
  disparity between the two
- you are sure that the feature is well understood by the doc writer and
  that there are no misinterpretation on what $option does
- the documentation is always up-to-date
- it forces the developer to think twice before implementing things that
  are too complicated to deploy since they'll have to write and explain
  how to do it

Then, the doc team is free to jump-in at anytime and review the doc.
Though I never saw anyone from the doc team review doc on Gnocchi – but
I guess they're too busy with other projects making them writing their
doc. :-)

Now, it's very likely that we'll move that policy to Aodh and Ceilometer
during the next cycle.

Continuing to address OpenStack and its documentation as a single and
unified project, while we are in a Big Tent mode, hoping it's gonna
scale, seems to me unrealistic.

Cheers,
-- 
Julien Danjou
/* Free Software hacker
   https://julien.danjou.info */
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 800 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160323/3cd68cab/attachment.pgp>