<div dir="ltr"><div dir="ltr"><div dir="ltr">The Pulp community is beginning our drive to improve the user docs for Pulp 3.<span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"><br></span></div><div dir="ltr"><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"><br></span></div><div dir="ltr"><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Docs work is tracked with the redmine tags [Pulp 3, Documentation] and can be viewed from the query</span><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb gmail-m_-4163714078818251916gmail-url"><a href="https://pulp.plan.io/issues?query_id=128" target="_blank">: https://pulp.plan.io/issues?query_id=128</a></span>. (Note that the query is for "Documentation" OR "Pulp3", so shows more issues than we need to focus on here.)</div><div dir="ltr"><br></div><b>Action Required:</b></div><div>Please
have a look at the goals and the issues mentioned in "high priority
work" section.</div><div><br></div><div> If you have some extra time, please review some of the issues in the query or tag other issues you think should be included. There are a lot of issues, so it will take a
focused effort from multiple people to tackle.<br></div><div dir="ltr"><br></div><div><b>Work begun:</b><br></div><div dir="ltr"><div dir="ltr"> I've started by reading over our existing documentation for pulpcore. This etherpad was used for organizing and compiling issues. [0] <a href="https://docs.pulpproject.org/en/3.0/nightly/" target="_blank">https://docs.pulpproject.org/en/3.0/nightly/</a></div></div><div dir="ltr"><br><div dir="ltr"><div id="gmail-m_-4163714078818251916gmail-magicdomid1156" class="gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb gmail-m_-4163714078818251916gmail-b"><b>Docs Push Goals</b></span><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">:</span><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"></span><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"><br></span></div><div class="gmail-m_-4163714078818251916gmail-ace-line"><ul><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Address OSAS Feedback </span><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb gmail-m_-4163714078818251916gmail-url"><a href="https://pulpproject.org/2018/09/17/pulp-community-health-audit/" target="_blank">https://pulpproject.org/2018/09/17/pulp-community-health-audit/</a></span></li></ul></div><div class="gmail-m_-4163714078818251916gmail-ace-line"><ul class="gmail-m_-4163714078818251916gmail-list-bullet2"><ul><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Add quickstarts</span></li><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">make pups visible on <a href="http://pulpproject.org" target="_blank">pulpproject.org</a></span></li><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">community visible calendar</span></li></ul><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Collaborative effort coordinated via Redmine</span></li><li>File issues for documentation gaps<br></li><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Close irrelevant/dupes/already-done issues<br></span></li><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Burn down<br></span></li></ul></div><div id="gmail-m_-4163714078818251916gmail-magicdomid4164" class="gmail-m_-4163714078818251916gmail-ace-line"><br></div><div class="gmail-m_-4163714078818251916gmail-ace-line"><div id="gmail-m_-4163714078818251916gmail-magicdomid6070" class="gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb gmail-m_-4163714078818251916gmail-b"><b>High Priority Work:</b></span></div><div class="gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb gmail-m_-4163714078818251916gmail-b">From
the review below, 2 important changes should be addressed
early in the docs push. These issues would benefit from feedback, please review and comment!<br></span></div><div class="gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb gmail-m_-4163714078818251916gmail-b"></span></div><div id="gmail-m_-4163714078818251916gmail-magicdomid6873" class="gmail-m_-4163714078818251916gmail-ace-line"><ul class="gmail-m_-4163714078818251916gmail-list-bullet2"><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Explicitly define which features will be documented by pulpcore, and which will be documented by each plugin</span></li><ul class="gmail-m_-4163714078818251916gmail-list-bullet1"><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb gmail-m_-4163714078818251916gmail-url"><a href="https://pulp.plan.io/issues/4626" target="_blank">https://pulp.plan.io/issues/4626</a></span></li><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">The division criteria (discussed on the issue) needs to be more concrete<br></span></li></ul><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Publish better REST API documentation for pulpcore</span></li><ul class="gmail-m_-4163714078818251916gmail-list-bullet2"><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Publish the live-api docs (many options): <a href="https://pulp.plan.io/issues/4636" target="_blank">https://pulp.plan.io/issues/4636</a><br></span></li><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Document how to ^ for plugin writers: <a href="https://pulp.plan.io/issues/4637" target="_blank">https://pulp.plan.io/issues/4637</a><br></span></li></ul></ul><div><br></div></div></div><b>State of the docs, and what can be improved:</b></div><div dir="ltr"> The docs appear to be in pretty good shape, but have some work left to do.<br></div><div dir="ltr"><div class="gmail-m_-4163714078818251916gmail-ace-line"><br></div><div id="gmail-m_-4163714078818251916gmail-magicdomid4918" class="gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">The
content of the current docs is mostly strong and concise [biased by familiarity]. The
organization is fine, though some clean-up would improve readability, and clarity of the left-bar main divisions. Isolated problems are
mentioned in the read-through notes on the planning etherpad. [0]<br></span></div><div id="gmail-m_-4163714078818251916gmail-magicdomid4920" class="gmail-m_-4163714078818251916gmail-ace-line"><br></div><div class="gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">The
division of the docs (between pulpcore and each plugin) requires prior
knowledge and is not well communicated. Based on the consistency, the developers have a shared understanding of which features should be documented in pulpcore, and
which topics are owned by the plugin. In my opinion, most of the
documentation on pulpcore is in the right place. The Plugin docs are off
to a good start by covering each major feature with quickstart-style
guides. Pulcore and each plugin's docs need to include more specific information, which
should be covered by the REST API docs.<br></span></div><div id="gmail-m_-4163714078818251916gmail-magicdomid5629" class="gmail-m_-4163714078818251916gmail-ace-line"><br></div><div id="gmail-m_-4163714078818251916gmail-magicdomid6011" class="gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">REST
API documentation is published on pulpcore's read the docs, but it is
missing too much information, rendering it practically useless. <a href="https://docs.pulpproject.org/en/3.0/nightly/integration-guide/rest-api/index.html#pulpcore-rest-api" target="_blank">https://docs.pulpproject.org/en/3.0/nightly/integration-guide/rest-api/index.html#pulpcore-rest-api</a>
. Significantly better REST API docs can be viewed at the docs endpoint
on a live-running pulp instance. The live REST API documentation
partially fills the gap between the quickstart docs (major feature) and
how that workflow can be altered (minor features). Unfortunately, these
docs are not published, they are only available if the user takes the
extra step of generating the documentation.</span></div><div class="gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"><br></span></div><div class="gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"><b>Plan:</b></span></div><ol><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Begin
by improving the REST API docs-- their inclusion will add a lot of
"missing" information. This will affect a lot of the following docs
work, allowing plugin writers to link to specific API calls, reducing
the need and length for text explanations. <br></span></li><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Clarify
any discrepancy about what is expected to be documented by each plugin.
This needs to be very clear to users, qe, and anyone who contributes
docs, especially plugin writers. Necessary for successful documentation
navigation.<br></span></li><li><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Understand, revise, and groom issues from the docs planning backlog</span></li></ol><div class="gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"><br></span></div><div class="gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"></span><br></div></div>[0] <a href="https://etherpad.net/p/Pulp3_Docs_Planning" target="_blank">https://etherpad.net/p/Pulp3_Docs_Planning</a></div></div>