Open Stack

Hi all,

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..

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.

Before you jump the gun and challenge the above said, let me give you few
examples to justify my words:


   - Going to docs.openstack.org page i can't easily figure out:
      - the Openstack version for which the documents were written =>
      current mean nothing to a beginner.
      - 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)?
      - 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
      - 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?
      - 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
      - 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 Python
      Developer Documentation
      <http://docs.openstack.org/developer/openstack-projects.html> to
      access all the core information. IMO anyone including the operator should
      know the HEAT spec so is not targeting the developers
      - If you access http://docs.openstack.org/developer/heat 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


   - A lot of good information are mixed between Wiki and blueprints but
   are not exposed in a organized way on the wiki or docs.openstack.org
   - 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:
      - 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
   - 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?


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.


Let me know what your view is?


Cheers,

Dani
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20141024/e1332f92/attachment.html>