<div dir="ltr"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Hi all, </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Anne here - your friendly documentarian!</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">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.</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">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.</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px"> </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">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:</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">- Contributors who make OpenStack</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">- Deployers who configure OpenStack</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">- Operations pros that run OpenStack</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">- End users who consume and administer OpenStack</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">But the docs’ contributor base is not growing at the same rate as our audiences.</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Why not? The responses to my recent survey about doc contributions indicate that the top barriers to docs’ contributions are:</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">- Tools: DocBook and WADL are difficult</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">- Doc locations: Lack of knowledge about where docs belong </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">- Process: Git/gerrit as process</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">- 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.</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">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.</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">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.</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">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.)</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Experience: </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Solution must be completely open source </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Content must be available online </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Search engines must be able to index </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Content must be searchable </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Content should be easily cross-linked by topic and type (priority: low) </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Enable comments, ratings, and analytics (or </span><a href="http://ask.openstack.org/" target="_blank" style="font-family:arial,sans-serif;font-size:12.727272033691406px">ask.openstack.org</a><span style="font-family:arial,sans-serif;font-size:12.727272033691406px"> integration) (priority: low) </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Distribution: </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Readers must get versions of technical content specific to version of product </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Modular authoring of content </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Graphic and text content should be stored as files, not in a database </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Consumers must get technical content in PDF, html, video, and audio </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Workflow for review and approval prior to publishing content </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Authoring: </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Content must be re-usable across authors and personas (Single source) </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Must support many content authors with multiple authoring tools </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Existing content must migrate smoothly </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">All content versions need to be comparable (diff) across versions </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Content must be organizationally segregated based on user personas </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Draft content must be reviewable in HTML </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Link maintenance - Links must update with little manual maintenance to avoid broken links and link validation</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">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.</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">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. </span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<br style="font-family:arial,sans-serif;font-size:12.727272033691406px"><span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Thanks,</span><br style="font-family:arial,sans-serif;font-size:12.727272033691406px">

<span style="font-family:arial,sans-serif;font-size:12.727272033691406px">Anne</span><div style="font-family:arial,sans-serif;font-size:12.727272033691406px"><br>[1] <a href="http://junodesignsummit.sched.org/event/626a1e21babaf30d98973f5eb7402fcf" target="_blank">http://junodesignsummit.sched.org/event/626a1e21babaf30d98973f5eb7402fcf</a> <div>

[2] <a href="https://docs.google.com/spreadsheet/ccc?key=0AhXvn1h0dcyYdFNaQW1OaVNNejZzYlRMZjBnT0pLMVE&usp=sharing" target="_blank">https://docs.google.com/spreadsheet/ccc?key=0AhXvn1h0dcyYdFNaQW1OaVNNejZzYlRMZjBnT0pLMVE&usp=sharing</a></div>

</div></div>