Re: [Openstack-doc-core] doc process and coders

[Razique Mahroua]

Nuage & Co - Razique Mahroua  razique.mahr...@gmail.com Le 30 avr. 2012 à 23:46, Anne Gentle a écrit : Glad you found it interesting! It sure piques my interests. Couple more comments below. On Fri, Apr 27, 2012 at 8:08 AM, Razique Mahroua <razique.mahr...@gmail.com> wrote: 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 Yeah no one wants to do maintenance... but it's the only way to gain trust in the docs. We need more investment from companies paying writers to work on docs, methinks.   - 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 So I'm starting to wonder if we should let the distros own the "starter" docs, and we own more advanced operations docs? The mailing list thread this morning with the new documents cropping up all the time has me wondering "aloud" about this. Would love your thoughts here. The thing is by letting the starter doc being driven by distros, we make the update process longer - maybe keep the most used ones for the starter doc (Fedora- CentOS/ Ubuntu-Debian) ?   - 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 targeted 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...) Interesting idea. Let me think about how to act on that.   - Doc writers/  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 My first goal is to get coders to mark a review as "DocImpact" so we get notified. Not that they get to throw it over the wall, but that we can review docs added and require that draft docs go in with a new feature. What is DocImpact especifically ? A "flag" that mean doc update will be required ?   - 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 Maybe we should also requests that blueprints get marked "DocImpact" - what do you think? If the DocImpact is what I think it is, then yes totally    - 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.  Agree... I'm still flummoxed by how often the Cactus release comes up in searches. Guess I need to do those redirects.   What do you think ? One additional HUGE impact to me is that teams that started with wikis moved to something more systematic. Their line is "We also found that all contributors who originally selected a public wiki to host their documentation eventually moved to a more controlled documentation infrastructure because of the high maintenance costs and the decrease of documentation authoritativeness." This line is the one I keep drawing... but I would like to integrate more tightly with Github for fast fixes. Would love ideas and implementation help there! The workflow today seems pretty solid IMHO - there is just that repo. subtility (gerrit/ origin) to keep in mind - I don't know though when we'll figure out the i18n routine how it will goes. BTW : I've missed the mails about the translations of the doc. Is there something to know that is already available/ work in progress ? Best Regards, Razique Thanks, Anne Razique Nuage & Co - Razique Mahroua  razique.mahr...@gmail.com <NUAGECO-LOGO-Fblan_petit.jpg> Le 25 avr. 2012 à 23:28, Anne Gentle a écrit : Hi all, We had a great discussion at the Design Summit about documentation processes and how difficult it is to become a doc contributor and keep the docs accurate. As promised, I dug up the fascinating McGill University study about open source doc projects. They found that you shouldn't separate doc process too far from coding process. I've attached the PDF. Would love to hear your feedback and applications for OpenStack. Some excerpts from the PDF: "We conducted an exploratory study to learn more about the documentation process of open source projects. Specifically, we were interested in identifying the documentation decisions made by open source contributors, the context in which these decisions were made, and the consequences these decisions had on the project. We performed semi-structured interviews with 22 developers or technical writers who wrote or read the documentation of open source projects. In parallel, we manually inspected more than 1500 revisions of 19 documents selected from 10 open source projects." "The programming language of the projects varied greatly: Perl (2 contributors), Java (2), _javascript_ (1), C(2), C++ (1), PHP (2), Python (2). The age of the projects ranged from 1.5 years to more than 15 years with an average of 8.7 years." "7. CONCLUSION Developers rely on documentation to learn how to use frameworks and libraries and to help them select the open source technologies that can fulfill their requirements. Following a qualitative study with 22 documentation contributors and users and the analysis of the evolution of 19 documents, we observed the decisions made by open source contributors in the context of three production modes: initial eff ort, incremental changes, and bursts. Understanding how these decisions are made and what their consequences are can help researchers devise documentation techniques that are more suited to the documentation process of open source projects and that alleviate the issues we identified. Our findings can also help practitioners make more informed decisions. For example, a better understanding of embarrassment-driven development could motivate developers to document their changes quickly after making them. A better comprehension of the relationship between the type of project (e.g., library or framework) and getting started and reference documentation could help contributors focus their e ffort on the more appropriate type of documentation." Thoughts? Anne <fse2010.pdf>-- Mailing list: https://launchpad.net/~openstack-doc-core Post to     : openstack-doc-core@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack-doc-core More help   : https://help.launchpad.net/ListHelp

-- 
Mailing list: https://launchpad.net/~openstack-doc-core
Post to     : openstack-doc-core@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack-doc-core
More help   : https://help.launchpad.net/ListHelp