openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Hi all -
Thanks everyone for the hard work at the Essex Doc Day this week! We
still have nearly 20 doc reviews in the queue :
https://review.openstack.org/#q,status:open+project:openstack/openstack-manuals,n,z
so please review and see if your favorite doc bug was fixed!

Several discussions came up at Doc Day that I wanted to bring to the
larger group. Feel free to comment as you see fit.

_Information architecture_
On further investigation, I believe the Image Admin manual and
Identity Admin manual can go away and the information be absorbed in
to the Compute Admin manual and the Object Storage admin manual as
they are supporting projects for the Compute and Storage end-goals.
These documents were sourced from RST dev docs, aren't well
maintained, and I think it's best to move towards a focus on Compute
and Storage admin manuals based on web analytics and available
resources.
Anthony has an outline at http://etherpad.openstack.org/drs6dPNF4p for
a User Guide that doesn't current exist and a Compute Administration
Guide that is similar to the current guide but contains more
information and a more logical flow.

Actions:
- Anne to remove the Identity Admin manual and Image Admin manual so
they will not be separate documents for the Essex release.
- Anne to place the relevant content into the Compute Admin manual.
- All: review outlines at http://etherpad.openstack.org/drs6dPNF4p and
comment inline
- Anne to determine source (or lack of) of each "topic" in Anthony's
admin manual outline.

_Doc accuracy_
Jesse voices a concern about the overhead XML brings to quick doc
fixes and when on boarding developers asking them to use a special
tool outside of their workflow like Oxygen. Inaccuracies that his team
is most likely to have the knowledge to spot and correct are difficult
to fix. Launchpad for doc bugs is not a favorite toolset.
Actions:
- Log doc bugs, review fixes to those bugs.

_Doc workflows_
Jesse Andrews and members of the Rackspace Cloud Builders (RCB) team
voiced a concern about new authoring and maintenance tasks, he senses
that the XML requirement is too hefty for developer contributors. He
would rather have devs write all the documents. Anne thinks that the
distro contributors are more likely to use DocBook and Jay Pipes
agreed.

Here are some specific authoring requirements and review requirements
for Python devs, which I'll try to describe in detail here. Please
update as you see fit:
As a Python dev, I want to author in command-line tools already in my
Python toolset that are already installed and familiar to me so that
my workflow is not interrupted.
As a Python dev, I want to locally build and view output from the
command line just as it appears on the docs site including the landing
pages so that I can see the changes due to my edits.
As a Python dev, I want to review other author's work without viewing
XML source so that the changes in the patch are easily discernible.

Here are some specific authoring requirements for doc contributors.

As a doc contributor, I want to review other contributor's work as
HTML output with markup so that I can see their changes quickly rather
than building locally.
As a translator, I want to have document strings presented in tools
that are familiar to me with changes being easy to discern.
As a translator, I want a known frozen release set of English
documents to be translated to another language so that I can work on a
document with good faith that the content remains accurate through the
translation process.
As a doc contributor, I have needs for markup that ensure numbered
list continues numbering even when code samples or program listings
are part of the list item.
As a doc contributor, I have certain document conventions that need
output to be distinguished as described in
http://wiki.openstack.org/Documentation/Conventions.
As a doc contributor, I need to ignore whitespace and XML formatting
so that doc reviews are easier to complete regardless of the authoring
tool.
There are also audience needs.
As a document commenter, I need to understand the chunking of the
content so I know what pice of content (page or section) to place a
comment on.

Actions:
- Anne to create a blueprint for openstack-manuals to be discussed at
the Summit specifically to address the reviewing difficulties.
- Jesse and team to scope work on an RST-only workflow for developers,
using one small deliverable as a test case.

_Doc tool chain source_
Matt Stephenson, an attendee at the Doc Day wants to see how he could
contribute to the Maven plugin.
Action:
- Joe Savak to inform OpenStack community of timeline for
contributions to the Maven plugin.

I really appreciate all the hard work on docs this release. Let's keep
the energy going for the next three weeks.
Warmly,
Anne