| Woaw, pretty interesting documents. Here are the several things I've noticed, and i agree with : - The documentation efforts as phases (initial launch, maintenance and burst) The lowest phase in term of production seems to be the maintenance phase - which in fact seems to require much investment/ effort compared to the other phase. The two others requiring a shorter investment when it comes to the total - Starter guides : best weapon for the success of the documentation The starter guides are awesome, they allow new users to discover the project, and help them to have a working implementation without reading extended docs, which is a key in the adoption of a project. The point here is being able to quickly evaluate a project and see how it goes. The starter guide doesn't need to cover everything, rather, it should be the reflect of the "all-in-one" derived from a project (i'm thinking here about the stackops distro, or the "appliances" for other projects). I think we should focus a bit more about the usability of starter docs, they should have their own identity - Marketing There is a part about the "marketing" of a project, which likely would help to bring more contributors. The number of contributors increased for projects with a great marketing. I think the starter guides could play a part in it - Features snippet Some user want a quick and straight answer for a question they might have ; it is necessary to make sure those answers could be provided quickly, not buried under pages of concepts and presentations. I think the API doc (api.openstack.org) is a great achievement in that way :-) - Areas focusing It would help me/us to have targetted sessions (like the Docblitz) OPS has hundreds of features, sometimes it's just hard to pick a topic and work on it. Sometimes I just sort by heat, sometimes by status, etc... having doc sessions focusing on one area would enhance productivity AND quality of the documentation (Week 1 : HA, week 2 : Proof-of-concepts, Week 3: Interfaces, etc...) - Doc writters/ Coders : different moving speeds Codes moves way faster than the documentation. Wouldn't it be possible to find a way of regulating that ? Maybe make sure a chunk of mandatory doc is committed along the code ? That would help us to pick the new features and write doc about, rather than systematically install the new version and install (which requires more time than simply reading, and adapting the documentation - Motivation New features are exciting, and I quite enjoy document them rather than updating for the 15th time a part of a documentation :-) it would be interesting to gather new features docs. and doc that belong to the same category. It would be easier to update the doc in a row for both - Usability Giving the possibility to a user to find what he looks for in a documentation is crucial. Performant search engines are as important as the doc itself. What do you think ? Razique Nuage & Co - Razique Mahroua
Le 25 avr. 2012 à 23:28, Anne Gentle a écrit : Hi all, |
-- Mailing list: https://launchpad.net/~openstack-doc-core Post to : [email protected] Unsubscribe : https://launchpad.net/~openstack-doc-core More help : https://help.launchpad.net/ListHelp
