Things we need to do to get ready for doc sprint

finish up doc team infrastructure type stuff - see the "what we should do" section in : http://www.nabble.com/A-proposal-for-a-way-forward-and-a-call-for-volunteers-tf3217105.html

What we should do
=================

Here is a set of action points that have come out of our previous
discussions, as well as brainstorms with Alex and others.

  - Produce a documentation guide -  DONE

:: Requires: 1 volunteer to pull it together and own it

This should be a short Tutorial, and incorporate style guidelines,
structural guidelines for the main types of documentation (How-to,
tutorial, manual), and general tips on writing good documentation. A lot
of this work has been started and discussed in the past few weeks.

  - Produce templates for each type of documentation -

:: Requires: 1 volunteer to extend PHC to support documentation
templates, 1 volunteer to collect and manage the templates themselves

When a new how-to, tutorial or manual is created, it should be
pre-populated with suggested headings (for how-tos, in particular) and
sections (for tutorials and manuals), such as "Introduction", "Who is
this for?" and "Conclusion". People should be free to change this if
they feel it's appropriate. Imposing this structure on all existing
documentation is explicitly *out* of scope at this time. The purpose is
to give people a starting point, not force them into an arbitrarily
decided structure. The sections are not metadata.

  - Produce better metadata, including ratings, for documentation -

:: Requires: 1 volunteer to extend PHC to support additional metadata,
ratings

In the first instance, documentation pieces should be ratable. We should
make views that make use of ratings to highlight popular documentation.
Ratings can be as simple as "was this useful yes/no", possibly with a
third option for "is this obsolete or incorrect?" We should extend the
existing PHC stats tools to make it easier to search for "bad"
documentation that is flagged up.

We may also decide to capture additional metadata provided (a) it has a
clear purpose; (b) existing documentation does not need to be reviewed
one-by-one to make the metadata useful; and (c) it does not place
unnecessary burdens on documentation authors.

  - Produce and document ongoing documentation processes -

:: Requires: 1 volunteer to own the process documents and coordinate others

Currently, we work in a very ad-hoc manner. This means that things end
up staying in the plone.org review queue for a long time, for example.
It also means that we don't have a good plan when a new version of Plone
is released, we don't necessarily anticipate changes, we don't know when
and how to take things out of the documentation issue tracker, and so on.

The main "ongoing" tasks of the docs team should be documented in a
single, concise document. These practices should be lightweight and
recognise that people have limited time. They should also be followed,
and the owner of the processes should have a license to cajole people
into helping out. This also helps us answer questions like: "Hi, I'm new
here, how can I help out with documentation?" in terms of specific
actions that volunteers can take, without needing to spend a lot of time
working out how we work (if at all).

  - Produce "trails" of documentation -

:: Requires: 1 volunteer to document and promote the "trails" mechanism,
1 volunteer to choose and structure a pilot "trail", and possibly others
to contribute to the trail.

This is by far the best idea we've had, and the most concrete task. To
summarise, instead of aiming for perfection across all documentation, we
should pick up a few key topics that we reckon most members of a
particular audience would need to know. Examples may be "Connecting to
LDAP and other user sources" or "Developing new content types." This
"front-line" documentation should be thought through in more depth than
the rest of the how-tos and short tutorials.

The idea is that people have a small number of places to start from, and
can then search for more specific documentation (over which we exercise
less tight control) once they have solid fundamentals. This makes a
manageable task out of an enormous one. It is not quite as good as
starting from scratch and producing a "Plone book," but it can be more
than good enough for audiences who just want some authoritative
information, and are willing to connect some of the dots themselves.

I propose that we start with a single trail as a pilot. Whoever
volunteers for this gets to pick. A trail should be a Reference Manual
(we'll use the sections and audiences to ensure they end up on top,
possibly also a Smart Folder or template to show them more prominently).

The first step in defining a new trail is to work out the best learning
path for the intended audience and assess this against existing
documentation. From this, a workable structure of sections and
placeholder pages should be created. Some kind of gap analysis needs to
be completed to find out how the documentation we've got already matches
what we want. Then, one of four things may happen:

(1) We link to existing how-tos and tutorials from a particular page in
the trail. There will probably be a short intro with context to save
users from having to browse through documentation that happens not to be
relevant to them.

(2) We find existing documentation that's close, but not quite good
enough. We fix it up, possibly asking for help from the original authors
or experts in the community, and apply some pressure to make it happen
quickly.

(3) We solicit new documentation, either by writing it ourselves or
asking something else nicely. Again, we prioritise this work and try to
reward people for producing something in days and weeks rather than months.

(4) We leave that part of the trail blank. We can publish a trail that's
not yet fully complete if some nice-to-have sections are missing but
it's otherwise useful. Having clearly defined holes to fill help get
things completed.

I'll stop there. I'm explicitly leaving out specific such as "deal with
Plone 3," because ideally it should be a consequence of the processes we
come up with.

set up doc team test plone for screen shots/ testing. clean install...possibly set up different versions?

inventory- what needs to be done

what's critical? what docs are most important to produce/update?

3.0 related docs are a priority but what else?

integrate comments into current docs

review audience and section categories of current docs (e.g. Cleaning up the End User portion of the How-to main page)

get doc tasks into doc tracker and assign to sprinters

find SMEs if needed to validate technical info

set up a plan to move forward after sprint- figure out a way to keep momentum going. review cycle??