Open Stack

On Fri, Oct 24, 2014 at 10:11 AM, Daniel Comnea <comnea.dani at gmail.com>
wrote:

> 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..
>
>
Of course! Welcome to the community. I'm the docs program technical lead so
I'm happy to dig in here.


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


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

>
>    - 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)?
>
> Havana is EOL as shown here: https://wiki.openstack.org/wiki/Releases so
we don't have it readily available in that dropdown list. That said, we
only deleted anre redirected docs.openstack.org/grizzly last week, and you
can get to http://docs.openstack.org/havana/ still. So it's purposeful and
full of intent. :)


>
>    - 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
>
> 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
https://wiki.openstack.org/wiki/Documentation/ContentSpecs


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

>
>    - 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
>
> We tend to hide releases and the inprogress docs in the custom search
engine on docs.openstack.org. In the redesign scoped searches will be
improved.


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

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.


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


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

>
>    - 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
>
> You want https://blueprints.launchpad.net/nova/juno 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.


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


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

Thanks for reporting all these with your fresh eyes.

Anne


> Let me know what your view is?
>
>
> Cheers,
>
> Dani
>
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20141024/0a5c5295/attachment-0001.html>