<div dir="ltr"><div>Hi Austin,</div><div>Thank you for pulling this all together and sharing it out.</div><div><br></div><div>2 thoughts:</div><div>1. What is the difference btween ln 34 & 127 of the [0] etherpad? Looks like a repeat to me.</div><div>2. I'd like to hear more about this idea of not being able to distinguish if a feature is documented in pulpcore or a plugin. Who is the audience for this document? If it is the user, I would dig a little deeper question as assumption that a user should have to know where it's documented. I would think if I really do need to know, then I'm looking for different, more general, high level information about the feature. If I'm a user of a specific plugin then I'm looking for how this feature works for a specific plugin and so therefore we might be able to re-use details - but what if this plugin decided not to use this feature or customized it somehow.  Granted I think we need to make this super easy to document if a plugin is using a feature in a straightforward way but do we need to make it customizable or have additional info specific to a plugin? In order to not make suggest a large change, I'd say, why not allow users to find the feature details within the plugin docs?</div><div><br></div><div>-Robin<br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Apr 3, 2019 at 1:32 PM Austin Macdonald <<a href="mailto:austin@redhat.com">austin@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><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_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"><br></span></div><div dir="ltr"><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"><br></span></div><div dir="ltr"><span class="gmail-m_6042055438540538117gmail-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_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb gmail-m_6042055438540538117gmail-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_6042055438540538117gmail-m_-4163714078818251916gmail-magicdomid1156" class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-b"><b>Docs Push Goals</b></span><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">:</span><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"></span><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"><br></span></div><div class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><ul><li><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Address OSAS Feedback </span><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb gmail-m_6042055438540538117gmail-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_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><ul class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-list-bullet2"><ul><li><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Add quickstarts</span></li><li><span class="gmail-m_6042055438540538117gmail-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_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">community visible calendar</span></li></ul><li><span class="gmail-m_6042055438540538117gmail-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_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Close irrelevant/dupes/already-done issues<br></span></li><li><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Burn down<br></span></li></ul></div><div id="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-magicdomid4164" class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><br></div><div class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><div id="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-magicdomid6070" class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-b"><b>High Priority Work:</b></span></div><div class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb gmail-m_6042055438540538117gmail-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_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-b"></span></div><div id="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-magicdomid6873" class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><ul class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-list-bullet2"><li><span class="gmail-m_6042055438540538117gmail-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_6042055438540538117gmail-m_-4163714078818251916gmail-list-bullet1"><li><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb gmail-m_6042055438540538117gmail-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_6042055438540538117gmail-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_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Publish better REST API documentation for pulpcore</span></li><ul class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-list-bullet2"><li><span class="gmail-m_6042055438540538117gmail-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_6042055438540538117gmail-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_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><br></div><div id="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-magicdomid4918" class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_6042055438540538117gmail-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_6042055438540538117gmail-m_-4163714078818251916gmail-magicdomid4920" class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><br></div><div class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_6042055438540538117gmail-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_6042055438540538117gmail-m_-4163714078818251916gmail-magicdomid5629" class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><br></div><div id="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-magicdomid6011" class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_6042055438540538117gmail-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_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"><br></span></div><div class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"><b>Plan:</b></span></div><ol><li><span class="gmail-m_6042055438540538117gmail-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_6042055438540538117gmail-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_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb">Understand, revise, and groom issues from the docs planning backlog</span></li></ol><div class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-author-a-lu99h8yvmz67zz88zef5z87zb"><br></span></div><div class="gmail-m_6042055438540538117gmail-m_-4163714078818251916gmail-ace-line"><span class="gmail-m_6042055438540538117gmail-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>
_______________________________________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman/listinfo/pulp-dev</a><br>
</blockquote></div>