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 */
signature.asc
Description: PGP signature
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
