Open Stack

Hi Anne,

Thanks for reply! I did my homework and i know who you are :)


You mentioned there is work taking place now to redesign it + other things
which are not ready for public eye. Can you point out where can i keep an
eye on it, maybe i'll be able to start review it/ contribute if i can?

In addition to this can i suggest to add the below video you uploaded on
youtube to Docs/HowToContribute ?


https://www.youtube.com/watch?v=rXzbNTqfJPU


I found it quite useful.


Cheers,
Dani




On Fri, Oct 24, 2014 at 4:38 PM, Anne Gentle <anne at openstack.org> wrote:

>
>
> 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/4f92379d/attachment.html>