<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Mon, May 22, 2017 at 4:39 AM, Alexandra Settle <span dir="ltr"><<a href="mailto:a.settle@outlook.com" target="_blank">a.settle@outlook.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">







<div bgcolor="white" lang="EN-US">
<div class="m_6947469957045664546gmail-m_-8077263033625277381WordSection1">
<p class="MsoNormal"><span style="font-size:11pt">Hi everyone,<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt">The documentation team are rapidly losing key contributors and core reviewers. We are not alone, this is happening across the board. It is making things harder, but not impossible.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt">Since our inception in 2010, we’ve been climbing higher and higher trying to achieve the best documentation we could, and uphold our high standards. This is something to be incredibly proud of.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt"> <u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt">However, we now need to take a step back and realise that the amount of work we are attempting to maintain is now out of reach for the team size that we have. At the moment we have 13 cores, of whom none are
 full time contributors or reviewers. This includes myself.</span></p></div></div></blockquote><div><br></div><div>One point I'd like to emphasize with this proposal, any way we go, is that we would prefer that the writing tasks not always fall on the devs, but that there can be dedicated writers or ops or end-users attending to info needs, it's just that they'll do the work in the repos. </div><div><br></div><div>Also, I'm working on a patch to try to quantify the best practices using our current data: <a href="https://review.openstack.org/#/c/461280/" target="_blank">https://review.<wbr>openstack.org/#/c/461280/</a> We may discover some ways to work that mean gaining efficiencies and ensuring quality. Project teams should consider changes to reviewers and so on to try to be inclusive of the varied types of work in their repo.</div><div><br></div><div>I'll emphasize that we need to be extremely protective of the user space with this sort of move. No one who reads the docs ultimately cares about how they are put together. They just want to find what they need and get on with their lives.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="white" lang="EN-US"><div class="m_6947469957045664546gmail-m_-8077263033625277381WordSection1"><p class="MsoNormal"><span style="font-size:11pt"><u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt">Until this point, the documentation team has owned several manuals that include content related to multiple projects, including an installation guide, admin guide, configuration guide, networking guide, and
 security guide. Because the team no longer has the resources to own that content, we want to invert the relationship between the doc team and project teams, so that we become liaisons to help with maintenance instead of asking for project teams to provide
 liaisons to help with content. As a part of that change, we plan to move the existing content out of the central manuals repository, into repositories owned by the appropriate project teams. Project teams will then own the content and the documentation team
 will assist by managing the build tools, helping with writing guidelines and style, but not writing the bulk of the text.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt">We currently have the infrastructure set up to empower project teams to manage their own documentation in their own tree, and many do. As part of this change, the rest of the existing content from the install
 guide and admin guide will also move into project-owned repositories. We have a few options for how to implement the move, and that's where we need feedback now.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt">1. We could combine all of the documentation builds, so that each project has a single doc/source directory that includes developer, contributor, and user documentation. This option would reduce the number
 of build jobs we have to run, and cut down on the number of separate sphinx configurations in each repository. It would completely change the way we publish the results, though, and we would need to set up redirects from all of the existing locations to the
 new locations and move all of the existing documentation under the new structure.</span></p></div></div></blockquote><div><br></div><div>I'd love to try this one. I know this is what John Dickenson has tried for the swift project with <a href="https://review.openstack.org/#/c/386834/" target="_blank">https://review.openstack.org/#<wbr>/c/386834/</a> but since it didn't match anyone else, and I haven't heard back yet about the user experience, we didn't pursue much. </div><div><br></div><div>I'll still be pretty adamant about the user experience, so that the project name does not spill over into the user space. Redirects will be crucial as someone pointed out in one of the recent etherpads. Also, it may require not publishing api-ref info to <a href="http://developer.openstack.org">developer.openstack.org</a> (in other words, one job means one target for publication right now).</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="white" lang="EN-US"><div class="m_6947469957045664546gmail-m_-8077263033625277381WordSection1"><p class="MsoNormal"><span style="font-size:11pt"><u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt">2. We could retain the existing trees for developer and API docs, and add a new one for "user" documentation. The installation guide, configuration guide, and admin guide would move here for all projects.
 Neutron's user documentation would include the current networking guide as well. This option would add 1 new build to each repository, but would allow us to easily roll out the change with less disruption in the way the site is organized and published, so
 there would be less work in the short term.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt">3. We could do option 2, but use a separate repository for the new user-oriented documentation. This would allow project teams to delegate management of the documentation to a separate review project-sub-team,
 but would complicate the process of landing code and documentation updates together so that the docs are always up to date.</span></p></div></div></blockquote><div><br></div><div>It's possible the data could point us in one direction or another (in-tree or separate repo for docs) but it's difficult to do a correlation for "success" of the docs when each project has multiple varied reasons for success. So I don't have an idea for a data-driven way to pick between 2 and 3 with the data we have today. </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="white" lang="EN-US"><div class="m_6947469957045664546gmail-m_-8077263033625277381WordSection1"><p class="MsoNormal"><span style="font-size:11pt"><u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt">Personally, I think option 2 or 3 are more realistic, for now. It does mean that an extra build would have to be maintained, but it retains that key differentiator between what is user and developer documentation and
 involves fewer changes to existing published contents and build jobs. I definitely think option 1 is feasible, and would be happy to make it work if the community prefers this. We could also view option 1 as the longer-term goal, and option 2 as an incremental
 step toward it (option 3 would make option 1 more complicated to achieve).<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt">What does everyone think of the proposed options? Questions? Other thoughts?</span></p></div></div></blockquote><div><br></div><div>My only other thought over coffee this morning is that an abstraction of "how it's made" is a healthy sign of maturation of a project. I'm a huge fan of WordPress and have maintained a blog on the platform for over a decade. I could care less how they write their docs, and that's a good thing.</div><div><br></div><div>Thanks for putting this together and thinking through options, Alex.</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="white" lang="EN-US"><div class="m_6947469957045664546gmail-m_-8077263033625277381WordSection1"><p class="MsoNormal"><span style="font-size:11pt"><u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt">Cheers,<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt">Alex<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt"><u></u> <u></u></span></p>
</div>
</div>

</blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="m_6947469957045664546gmail_signature"><div dir="ltr"><div><div dir="ltr"><div dir="ltr"><div dir="ltr"><div><br></div><div>Read my blog: <a href="https://justwriteclick.com" target="_blank">justwrite.click</a></div><div>Subscribe to Docs|Code: <a href="http://docslikecode.com" target="_blank">docslikecode.com</a> </div></div></div></div></div></div></div>
</div></div>