Structuring a document

This is focused at a fairly granular, how-to level. Tutorials or an end-to-end document, you should have some more narrative stuff with elements of this (numbering, tasks etc) mixed in

Purpose Statement

Start with a purpose statement up front...or at least something that says this is *exactly* what you are going to accomplish by following these steps

• saves the reader time because they know right away what this is or is not going to help them with
• always write it last so it reflects the steps exactly

Tagging

Tagging is probably going to play a big part in how we tie the smaller parts of documentation together into a cohesive whole.

• should tag stuff
• by topic or by type of user
• or by applicability e.g. Plone 2.5
• Tags need to be granular - one of the problems we have right now is with only a few "audience" tags everyone just picks all of them because they're all a bit related.
  

Prerequisites

Users need to know up front, what they need to do to complete a task

• important for howtos: full list of the prerequisites
• prereqs both for what you have to have installed and what skills or access rights you need
• when we have those prerequisites, we could also have links to pages that will help you fulfil the prerequisites

Task-based doco

At this level, a document should be broken down into how to complete one (and only one) task.

• Numbered steps!
• each step should be performing one action...like
  • 1) click here
  • 2) Hit "enter"
  • etc...
• no matter how small the action is, it's one action per numbered step
• though docs that are just lists of actions are a bit hard to read i guess... we should encourage people to do it like:
  explanation about what's going to happen
  1. foo
  2. bar
• Or:
  1. foo
  2. bar
  3. Result: bla bla bla

Decision Points

• use what i call if/then tables....if you want to do this, then go to step X, if you want to do this, then go to step Y
  

Problems with the current doco

From http://www.openplans.org/projects/plone-documentation/project-home

How could we solve some of these, by having better structured doco at the micro level?

Style Issues

We need a bit of stylistic consistency

• need something about textual/punctuation type guidelines
• standards of when to use numbers, bold, italics, arrows, etc
• standards on when to use Click vs. Press
• "typographic conventions"
• when we write guidelines, we should make them as *short* as possible
• We need a style guide
  

Notes on strategy

• we need to separate documentation into "blessed" and "the rest"
• Make the "blessed" stuff easier to find

The current situation

1. Stuff people *must* learn (depending on audience) vs. stuff people may want to know (marginal use cases)
2. Well-written vs. poorly-written (also -focused, -explained etc)
3. Canonical vs. overlapping documents

We want to:

1. Document the stuff people must learn (as opposed to the edge cases)
2. Have it well written (-focused etc)
3. Write canonical documentation

We have several audiences - end user, integrator, programmer etc. They all want to be able to find one, canonical, obvious, well-written source of doco for their respective needs.

Once those needs are met, I may have a specific thing I want to find, which may be quite particular to my use case or need

howtos= small stuff that doesn't fit anywhere else
tutorials = little semantic distinction from howtos, but are generally longer, better structured with steps etc
maybe we need "all doco is equal, but some is more equal than others" kind of approach
How to structure a framework that we can plug docs into:

 "if we had great docs on all of this, here's how we'd want people to read it, in this order"
: there are a multitude of use cases ... that may not be documented in teh "better written"
 then we find what we *do* have
we need a subject outline
then we could take that skeleton and create doc tasks off of it and know what needs to be created or cleaned up
 if we have "good enough" docs, we link it in, maybe with a paragraph or two to keep the trail flowing
 (so that people can e.g. skip a section they don't care about)
 if we're missing something, we try to commissino it
 when we have enough to make sense, we publish the trail
 and let people know that if you write documentation to this standard, you get to be a trail (also, you get a cookie)

trails trails trails....

What trails might there be?
End user coming to Plone for first time?
Plone for PHP/Perl/Pythong/Java developers?

(1) decide what we need docs on
(1a) agree which trails we need
(2) agree on guideilnes so we can tell what's good enough to be in a trail
(3) agree some general principles on how to structure trails and get stuff in there
(4) get ratings on PHC content
(5) make the damned trails (not necessarily in that order)

if we agree on some, we can also just create unpublished ref manuals right away

Start with a wiki page, then move to the tracker: http://plone.org/development/teams/documentation/documentation-tracker

The stuff below here is informational

References

• https://dev.plone.org/plone.org/wiki/GuidelinesForDocumentation

Concepts

macro-structuring vs micro-structuring

Tasks, misc

• Bring the contents of this page back into the dev.plone.org wiki
• a thing to talk about when we discuss macro-structure is the organization of different doc types
• advanced users will likely contain coding howtos and tutorials we should also have a link in there to the hopefully-to-come coding styleguide
• Mid-level docs are hard to find - the Z-shaped learning curve