Open Stack

Hi Ildikó,

Comments inline ...

On 27/01/17 20:12, Ildiko Vancsa wrote:
> Hi Docs Team,
> 
> TL;DR I have an old bug report for the Admin Guide which targeted the way how it is versioned, or maybe rather not versioned and which also implied other actions on that document, for which we weren’t ready at the time of reporting the issue.
> 
> The bug report is the following: https://bugs.launchpad.net/openstack-manuals/+bug/1458820
> 
> The bug report itself highlights that it is hard both from usage and from maintenance perspective to handle a document which contains information about at least three OpenStack releases in an iterative way. When someone tries to figure out what belongs to one single OpenStack release in it they need to put it together from an original state and the changes since that. In case of Telemetry we had issues with listing the collected meters in a user friendly way for instance.
> 
> Another big issue with the Admin Guide is the maintenance, which is tough with having the source files in a separate, centralized repository far away from the code where the changes happen. This way core reviewers have a hard time to keep the document in sync with the code as they cannot effectively -1 a code change as it *cannot* contain the doc changes.

I agree, it gets messy.

> 
> The reason I bring this up now again as I see the experiment with moving the Install Guide chapters to the project repositories a successful initiative, I remember seeing positive feedbacks about that move on the ML, etc. I think someone brought even up the Admin Guide as next candidate to a similar move.

We implemented the Deployment Guides in Ocata, and if we go by requests alone, then the Admin Guide is the next on the list.

> 
> I would like to ask the Docs Team for their opinions about this topic. I see a lot of advantage in having the documentation living together with the code and also having version controlled together with the code. This would also remove some of the burden from the Docs team as well, which I see a beneficial change too.
> 
> What is your view about this? Could this be a good topic for the upcoming PTG too maybe?

I think it's sensible to consider, at the very least. Can you add it to the PTG etherpad for discussion?

Lana

-- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 538 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20170130/767fb4db/attachment.pgp>