Re: [Plone-docs] Ideas to improve plone.org's documentation area

[Martin A. <opt...@gm...>]

Christian Schneider wrote:
> Hi all,
> I found it difficult to keep track of all the information that was 
> included in the posts of the "Let's revive The Definitive Guide to 
> Plone!" thread, so I created a project called "Plone Documentation 
> Standards and Guidelines" 
> (http://www.openplans.org/projects/plone-documentation/) on 
> openplans.org. I hope that wasn't precipitous thing to do, but I felt 
> like I needed a place to at least write down and properly explain my own 
> ideas. So if you feel like it, check it out, I have put the first page 
> up where I explain what I had in mind.
> Feel free to comment and participate... or to tell me to shut the whole 
> thing down again.

Hi Christian,

I think this is great - thanks for taking the initiative! We could use 
the wiki (http://dev.plone.org/plone.org/wiki/DocumentationTeam) and 
tracker on plone.org (http://plone.org/development/teams/documentation) 
but OpenPlans offers a nicer wiki if nothing else. I'd say that what we 
produce on OpenPlans should be first and foremost a workarea, and that 
real content ends up on plone.org not there, but other than that, I 
don't think it matters what tools we use.

The content there looks like a great start. I encourage you to continue 
to work on it, and to yell at this list regularly for review and 
follow-up. I'll put what time into it I can.

Once we work out some general guidelines, I suggest we write a how-to on 
plone.org (http://plone.org/documentation/how-to/write-documentation, to 
complement /read-documentation :)) that summarises it in a concise way.

The next steps will then probably be (in parallel) to categorise The 
Definitive Guide into bits that are useful as-is, salvageable with a bit 
of work, and outdated; and, to draft one or more ideal "trails" of 
documentation that we'd *like* to present our users. Then, we can match 
the steps of the trail to existing and lacking documentation and work to 
fill the gaps.

In the short term, I suggest that we use simple how-to documents to 
create the trails. We can use the categories on 
plone.org/documentation/how-to to organise it such that the "trail 
overview" documents end up at the top, much like the "How to read 
documentation" and a few other "high level" documents appear at the top 
now. Such a how-to would set out some background and a narrative, with a 
link to another how-to, tutorial or reference manual for each "step" of 
the trail.

This way, we avoid having to wait for new technology (e.g. a "trail" 
content type or what not) to be able to better organise things. We can 
introduce that later if need be, but my guess is that most people won't 
care.

Btw, the Java documentation uses the concept of trails in tutorials. I 
find that documentation a bit cumbersome to navigate, but we can 
probably learn a lot from what they've done!

Thanks again for leading on this and getting the momentum going. :)

Martin