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 _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
