openstack-doc-core team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

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.mahroua@xxxxxxxxx>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.


>
> *- 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.


> *- 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?


> - *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!

Thanks,
Anne


> Razique
>
> *Nuage & Co - Razique Mahroua** *
>  razique.mahroua@xxxxxxxxx
>
>
> 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
> <http://is.gd/TpxZbc>
> <fse2010.pdf>--
> Mailing list: https://launchpad.net/~openstack-doc-core
> Post to     : openstack-doc-core@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack-doc-core
> More help   : https://help.launchpad.net/ListHelp
>
>
>