<div dir="ltr">
Hi all, <br><br>Anne here - your friendly documentarian!<br><br>As the docs PTL, it’s my job to gather input about and make doc tool and process decisions. This note is the first step: Your responses to this note give me input to share at the Summit where, hopefully, we will form a consensus about process and tool changes. About a week after the Summit, I'll produce a roadmap for changes that we will implement as a community.<br>
<br>A recurring issue that I hope we can solve is barriers to doc contributions. Leading up to the Summit, I've gathered as much data as I can about these barriers. We have an awesome doc team and 20 core people on the team, but only about dozen people write and review the bulk of the cross-project documentation regularly. It's amazing we've accomplished all we have with the resources available. We have increased doc contributions by 10% since the last release, but even so, we must find ways to increase the doc contributor base.<br>
<br>Remember three and a half years ago? We had nova and swift and a web site for each. Fast-forward and we now have docs for multiple audiences:<br><br>- Contributors who make OpenStack<br>- Deployers who configure OpenStack<br>
- Operations pros that run OpenStack<br>- End users who consume and administer OpenStack<br><br>But the docs’ contributor base is not growing at the same rate as our audiences.<br><br>Why not? The responses to my recent survey about doc contributions indicate that the top barriers to docs’ contributions are:<br>
<br>- Tools: DocBook and WADL are difficult<br>- Doc locations: Lack of knowledge about where docs belong <br>- Process: Git/gerrit as process<br>- Subject-matter expertise: People do not have test environments and they feel that they don't know enough to contribute. Also, 70% of the respondents to the survey work on or consume OpenStack fewer than 10 hours a week.<br>
<br>It's not easy to interpret and analyze this data, but I believe we're not facilitating part-time OpenStack users to write docs and feel confident in their contributions.<br><br>To solve this problem, I want to explore possible changes to our doc tools and processes. We must engage more doc contributors to spread the doc creation and maintenance burden.<br>
<br>Tuesday at 12:05 in B304, [1] we're having cross-project documentation session to discuss this list of requirements for doc tools and process changes: (See [2] for spreadsheet format.)<br><br>Experience: <br>Solution must be completely open source <br>
Content must be available online <br>Search engines must be able to index <br>Content must be searchable <br>Content should be easily cross-linked by topic and type (priority: low) <br>Enable comments, ratings, and analytics (or <a href="http://ask.openstack.org">ask.openstack.org</a> integration) (priority: low) <br>
<br>Distribution: <br>Readers must get versions of technical content specific to version of product <br>Modular authoring of content <br>Graphic and text content should be stored as files, not in a database <br>Consumers must get technical content in PDF, html, video, and audio <br>
Workflow for review and approval prior to publishing content <br><br>Authoring: <br>Content must be re-usable across authors and personas (Single source) <br>Must support many content authors with multiple authoring tools <br>
Existing content must migrate smoothly <br>All content versions need to be comparable (diff) across versions <br>Content must be organizationally segregated based on user personas <br>Draft content must be reviewable in HTML <br>
Link maintenance - Links must update with little manual maintenance to avoid broken links and link validation<br><br>I want to gather input about these requirements before we discuss implementation. As far as tools go, some possible solutions are Markdown, reStructuredText (RST), AsciiDoc, each with its own build framework. I'm not anticipating a complete migration, but we need to solve these barriers for certain docs.<br>
<br>Please let me know your thoughts through the OpenStack-docs mailing list if you cannot attend in person. I am excited to hear your ideas, and I can't wait to meet a wider audience and serve more doc contributors. <br>
<br>Thanks,<br>Anne<div><br>[1] <a href="http://junodesignsummit.sched.org/event/626a1e21babaf30d98973f5eb7402fcf">http://junodesignsummit.sched.org/event/626a1e21babaf30d98973f5eb7402fcf</a> <div>[2] <a href="https://docs.google.com/spreadsheet/ccc?key=0AhXvn1h0dcyYdFNaQW1OaVNNejZzYlRMZjBnT0pLMVE&usp=sharing">https://docs.google.com/spreadsheet/ccc?key=0AhXvn1h0dcyYdFNaQW1OaVNNejZzYlRMZjBnT0pLMVE&usp=sharing</a></div>
</div></div>