Open Stack

Hi Matt,

I'm open to discuss what would be the best way forward in this topic. First of all I would like to understand the intention with document structures long term to see how we can have a scalable and maintainable process.

My experience is that keeping the documentation up to date separately from the code can be difficult that results in outdated materials, which also leads to bad user experience and impression.

Would this topic be sufficient for one of the team meetings?

Thanks and Best Regards,
Ildikó

> -----Original Message-----
> From: Matt Kassawara [mailto:mkassawara at gmail.com]
> Sent: May 07, 2016 00:55
> To: Ildikó Váncsa
> Cc: Lana Brindley; enstack.org; OpenStack Development Mailing List; openstack-i18n at lists.openstack.org
> Subject: Re: [OpenStack-docs] What's Up, Doc? 6 May 2016
> 
> One significant advantage of central documentation involves providing content in a single location with consistent structure or format
> that best serves the particular audience. Moving most or all documentation into project trees essentially eliminates this advantage,
> leaving our audiences with an impression that OpenStack consists of many loosely associated projects rather than a coherent cloud
> computing solution. However, as a contributor to a few other OpenStack projects who helps other developers contribute to central
> documentation, I can understand some of the frustrations with it. I prefer to resolve these frustrations and have some ideas that I
> intend to float in separate thread, but if you don't think that's possible, consider submitting a spec to change the primary purpose of
> the central documentation team to simply managing links to content in the project trees.
> 
> On Fri, May 6, 2016 at 10:03 AM, Ildikó Váncsa <ildiko.vancsa at ericsson.com> wrote:
> 
> 
> 	Hi Lana,
> 
> 	Thanks for the summary, it's pretty good reading to catch up what happened recently.
> 
> 	I have one question, I might missed a few entries, so please point me to the right document in this case. We had a
> docco session with the Telemetry team and we agreed on moving back the documentation snippets, like for instance the Install
> Guide, to the project trees is a really good step and we're very supportive. In this sense I would like to ask about the plans regarding
> the Admin guide. We have a chapter there, which is on one hand outdated and on the other hand would be better to move under the
> project trees as well. Is this plan/desire in line with your plans regarding that document?
> 
> 	Thanks,
> 	/Ildikó
> 
> 
> 	> -----Original Message-----
> 	> From: Lana Brindley [mailto:openstack at lanabrindley.com]
> 	> Sent: May 06, 2016 08:13
> 	> To: enstack.org; OpenStack Development Mailing List; openstack-i18n at lists.openstack.org
> 	> Subject: What's Up, Doc? 6 May 2016
> 	>
> 	> Hi everyone,
> 	>
> 	> I hope you all had a safe journey home from Summit, and are now fully recovered from all the excitement (and
> jetlag)! I'm really
> 	> pleased with the amount of progress we made this time around. We have a definitive set of goals for Newton, and I'm
> confident that
> 	> they're all moving us towards a much better docs suite overall. Of course, the biggest and most important work we
> have to do is to get
> 	> our Install Guide changes underway. I'm very excited to see the new method for documenting OpenStack installation,
> and can't wait
> 	> to see all our big tent projects contributing to docs in such a meaningful way. Thank you to everyone (in the room and
> online) who
> 	> contributed to the Install Guide discussion, and helped us move forward on this important project.
> 	>
> 	> In other news, I've written a wrapup of the Austin design summit on my blog, which you might be interested in:
> 	> http://lanabrindley.com/2016/05/05/openstack-newton-summit-docs-wrapup/
> 	>
> 	> == Progress towards Newton ==
> 	>
> 	> 152 days to go!
> 	>
> 	> Bugs closed so far: 61
> 	>
> 	> Because we have such a specific set of deliverables carved out for Newton, I've made them their own wiki page:
> 	> https://wiki.openstack.org/wiki/Documentation/NewtonDeliverables
> 	> Feel free to add more detail and cross things off as they are achieved throughout the release. I will also do my best to
> ensure it's kept
> 	> up to date for each newsletter.
> 	>
> 	> One of the first tasks we've started work on after Summit is moving the Ops and HA Guides out of their own
> repositories and into
> 	> openstack-manuals. As a result, those repositories are now frozen, and any work you want to do on those books
> should be in
> 	> openstack-manuals.
> 	>
> 	> We are almost ready to publish the new RST version of the Ops Guide, there's just a few cleanup edits going in now,
> so make sure you
> 	> have the right book, in the right repo from now on. This was our very last book remaining in DocBook XML, so the docs
> toolchain will
> 	> be removing DocBook XML support. See spec https://review.openstack.org/311698 for details.
> 	>
> 	> Another migration note is that the API reference content is moving from api-site to project specific repositories and
> api-site is now
> 	> frozen. For more detail, see Anne's email: http://lists.openstack.org/pipermail/openstack-docs/2016-
> May/008536.html
> 	>
> 	> == Mitaka wrapup ==
> 	>
> 	> We performed a Mitaka retrospective at Summit, notes are here: https://etherpad.openstack.org/p/austin-docs-
> mitakaretro
> 	>
> 	> In particular, I'd like to call out our hard working tools team Andreas and Christian, all our Speciality Team leads, and
> the Mitaka release
> 	> managers Brian and Olga. Well done on a very successful release, everyone :)
> 	>
> 	> Total bugs closed: 645
> 	>
> 	> == Site Stats ==
> 	>
> 	> Thanks to the lovely people at Foundation (thanks Allison!) I now have access to more stats than I could possibly guess
> what to do
> 	> with, and I'm hoping to be able to share some of these with you through the newsletter. If there's something in
> particular you would
> 	> like to see, then please let me know and I'll endeavour to record it here!
> 	>
> 	> So far I can tell you that docs.openstack.org had 1.63M unique pageviews in April, down slightly from 1.72M in March,
> and the average
> 	> session duration is just over six minutes, looking at just under 4 pages per session.
> 	>
> 	> == Doc team meeting ==
> 	>
> 	> Next meetings:
> 	>
> 	> We'll be restarting the meeting series next week.
> 	>
> 	> Next meetings:
> 	> US: Wednesday 11 April, 19:00 UTC
> 	> APAC: Wednesday 18 April, 00:30 UTC
> 	>
> 	> Please go ahead and add any agenda items to the meeting page here:
> 	> https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting
> 	>
> 	> --
> 	>
> 	> Keep on doc'ing!
> 	>
> 	> Lana
> 	>
> 	> https://wiki.openstack.org/wiki/Documentation/WhatsUpDoc#6_May_2016
> 	>
> 	> --
> 	> Lana Brindley
> 	> Technical Writer
> 	> Rackspace Cloud Builders Australia
> 	> http://lanabrindley.com
> 
> 
> 	_______________________________________________
> 	OpenStack-docs mailing list
> 	OpenStack-docs at lists.openstack.org
> 	http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 
>