<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Oct 24, 2014 at 10:11 AM, Daniel Comnea <span dir="ltr"><<a href="mailto:comnea.dani@gmail.com" target="_blank">comnea.dani@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div><div><div>Hi all,<br><br></div>I recently joined up the community and started to get my hands dirty using OpenStack and naturally the first contact was to start reading the documentation..<br><br></div></div></div></blockquote><div><br></div><div>Of course! Welcome to the community. I'm the docs program technical lead so I'm happy to dig in here.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div><div></div>Now i'll be very honest and blunt (that's how i am) and please don't take it as a critic but just as a very honest feedback: the whole OpenStack documentation and most importantly how it's organized is very poor.<br><br></div></div></blockquote><div><br></div><div>Agreed, and we have doc bugs and a re-design in the works now to address these issues. It has been a long time coming.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div></div>Before you jump the gun and challenge the above said, let me give you few examples to justify my words:<br><br><ul><li>Going to <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a> page i can't easily figure out:</li><ul><li>the Openstack version for which the documents were written => current mean nothing to a beginner.</li></ul></ul></div></blockquote><div><br></div><div>Noted. We've gone from /trunk which was truly meaningless to current but need to indicate what that means. I'm passing this on to the designers working on the redesign. </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><ul><ul><li>there is a link which can be easily missed(small fonts) which allows you to change to an older Openstack doc version however that goes back to only current -1 . What about current - 2 version (aka Havana)?</li></ul></ul></div></blockquote><div>Havana is EOL as shown here: <a href="https://wiki.openstack.org/wiki/Releases">https://wiki.openstack.org/wiki/Releases</a> so we don't have it readily available in that dropdown list. That said, we only deleted anre redirected <a href="http://docs.openstack.org/grizzly">docs.openstack.org/grizzly</a> last week, and you can get to <a href="http://docs.openstack.org/havana/">http://docs.openstack.org/havana/</a> still. So it's purposeful and full of intent. :)</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><ul><ul><li>Although a minor one it worth mention it => the majority of all documents have a date and Openstack version name - Havana/ IceHouse/ current but others have only a date in it</li></ul></ul></div></blockquote><div>We continuously publish everything except for Install Guides and Configuration Reference. So this is again on purpose. It's a good observation. You can read more about release-specific docs in <a href="https://wiki.openstack.org/wiki/Documentation/ContentSpecs">https://wiki.openstack.org/wiki/Documentation/ContentSpecs</a> </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><ul><ul><li>Getting training section is quite useful but it doesn't mentioned anything about the target version - can i rely on the data written inside - at the top - and assume is only for current version?</li></ul></ul></div></blockquote><div><br></div><div>This is a known issue and the training team continues to discuss solutions here. It tends to trail the release. Sean do you have comments for this question? </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><ul><ul><li>The search functionality is very limited - most of the time i find more useful info by searching directly from a search engine - bling/ google/ etc</li></ul></ul></div></blockquote><div>We tend to hide releases and the inprogress docs in the custom search engine on <a href="http://docs.openstack.org">docs.openstack.org</a>. In the redesign scoped searches will be improved.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><ul><ul><li>the most important missing point is that on the main page i can't find anything about Heat/ Nova/ Neutron specs => i need to click on <a href="http://docs.openstack.org/developer/openstack-projects.html" target="_blank">Python Developer Documentation</a> to access all the core information. IMO anyone including the operator should know the HEAT spec so is not targeting the developers</li></ul></ul></div></blockquote><div>Good observation. The specs site was only available about a month ago, and with the redesign coming, we hadn't considered how to ensure contributor devs can get to that site easily from docs. I purposely don't want a lot of specs published to docs as I believe specs are speculative and docs should be reality.</div><div><br></div><div>A next step in the docs redesign and architecture is to do a better job uncovering contributor docs. But with the growth of OpenStack, other audiences have taken top priority.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><ul><ul><li>If you access <a href="http://docs.openstack.org/developer/heat" target="_blank">http://docs.openstack.org/developer/heat</a> from a result returned by a search engine, i have no clue if is targeting the Current(although means nothing vs Juno or other code name) OpenStack version or older one etc</li></ul></ul></div></blockquote><div>We've struggled with this and heat takes a lot of heat on it. We have a new set of HOT template guides that aren't quite ready for public consumption that address this known issue.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><ul><li>A lot of good information are mixed between Wiki and blueprints but are not exposed in a organized way on the wiki or <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a></li></ul></div></blockquote><div><br></div><div>Yep. Stefano has done some good wiki cleanup work but the wiki is the junk drawer right now. And again, I don't want a lot of cross over from the wiki and docs.  </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><ul><li>The Blueprints are very useful as it provides a lot of low level info about the implementation however i couldn't find an easy way to be able to say:</li><ul><li>in Juno release, the following Blueprints were added => knowing this will also allow me to find out if the whole blueprint was completed or not by looking at the associated Gerrit IDs and see if they were merged or not</li></ul></ul></div></blockquote><div>You want <a href="https://blueprints.launchpad.net/nova/juno">https://blueprints.launchpad.net/nova/juno</a> and then substitute nova for each project name. I don't recall if there's a rollup url for all the integrated projects or not.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><ul><li>There is a ton of examples for HEAT which are scattered on Github/ RedHat RDO/ Rackspace/ Mirantis etc - can't all this be aggregated and added into the wiki so we can easily find them?</li></ul><p><br></p></div></blockquote><div>I'd love to see this happen as well. Again we have two new heat docs deliverables that aren't quite yet public, but they don't do this work and it's a good idea to add.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><p></p><p>My suggestion for fixing the majority of all this stuff is to adopt the Oracle database documentation portal which is focus on a release version but also adds/ correct other bits which i mentioned above.</p><p><br></p></div></blockquote><div>Oracle and IBM are exemplars but aren't OpenStack. We have certain requirements such as gerrit for reviews and open source tooling that don't match their approach. </div><div><br></div><div>Thanks for reporting all these with your fresh eyes.</div><div><br></div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><p></p><p>Let me know what your view is?</p><p><br></p><p>Cheers,</p><p>Dani<br></p><p> </p></div>
<br>_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br></blockquote></div><br></div></div>