<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>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>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">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><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><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><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><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><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">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><li>If you access <a href="http://docs.openstack.org/developer/heat">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><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">docs.openstack.org</a></li><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><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><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><p>Let me know what your view is?</p><p><br></p><p>Cheers,</p><p>Dani<br></p><p> </p></div>