Open Stack

On Fri, Oct 24, 2014 at 2:45 PM, Daniel Comnea <comnea.dani at gmail.com>
wrote:

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

If you look through the meeting logs (not that I'd expect you to) you can
find the design brief here:

https://docs.google.com/document/d/1GGKTKHDMc8A0jerdv-K3ql0udnxMr-j4DlhL2Cj6kcw/edit


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

We had it there for quite a while then it got outdated and stale so we
removed it. I guess you can add it back, it's a wiki page after all.

A more recent video is the recent bootstrap hour we had about developer
docs. Not a how-to exactly, but a good discussion.


   - Youtube Stream: http://www.youtube.com/watch?v=n2I3PFuoNj4
   - Etherpad: https://etherpad.openstack.org/p/obh-diving-into-docs
   - Slides: http://bit.ly/obh-diving-into-docs




>
>
> 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/9205668b/attachment-0001.html>