[OpenStack-docs] [User Guides] Reorganize User Guides Spec for Mitaka.
Lana Brindley
openstack at lanabrindley.com
Mon Oct 26 21:14:51 UTC 2015
I’m coming in late to this conversation, because travel. In short, though, I think I’m in agreement with most of you. Let’s avoid conditionals if we can, the Install Guide is hard enough as it is. I also like the idea of combining the guides if it’s possible. There’s a certain amount of complexity around the user guides, and readers are generally bad at self-selecting their ‘audience type’, and so go looking for content in all the wrong places. As we move towards a more EPPO-style body of content, our books should naturally be getting somewhat larger, so overall size isn’t bothering me too much at this point. As for number of files, like Andreas said, let the form follow the function.
L
On 24 Oct 2015, at 3:02 am, Anne Gentle <annegentle at justwriteclick.com> wrote:
>
>
> On Fri, Oct 23, 2015 at 1:10 AM, Joseph Robinson <joseph.robinson at rackspace.com> wrote:
> Hello all,
>
> For the M summit next week, I’ve put together a spec for reorganising the User Guides for the M release with the User Guides Team.
>
> https://review.openstack.org/#/c/238770/
>
> On some of the Proposed Changes:
>
> I raised number of files in the repository as a proposed change for visual reasons – file number has no effect on the build, but my thoughts are that smaller repos might make the guide easier to search and handle. This idea spun out of User Guide team talks during the conversion to .rst format.
>
> Conditionals was an (slightly naïve) idea I had for combining the guides together. A point for discussion here to eventually improve or change the docs spec – Should the User Guides be reorganised to have conditionals?
>
>
> In a word, no.
>
> Let's keep it simple rather than add complexity. The goal with the RST migration is simplification to enable more contributors as OpenStack grows. Users especially shouldn't have any further burden than they already do.
>
> Thanks for asking -
>
> Anne
>
> Best Regards,
>
> Joseph Robinson
> Information Developer I
> -------------------------------
> Joseph.Robinson at Rackspace.com
>
>
>
> Rackspace Hosting Australia PTY LTD a company registered in the state of Victoria, Australia (company registered number ACN 153 275 524) whose registered office is at Level 1, 37 Pitt Street, Sydney, NSW 2000, Australia. Rackspace Hosting Australia PTY LTD privacy policy can be viewed at www.rackspace.com.au/company/legal-privacy-statement.php - This e-mail message may contain confidential or privileged information intended for the recipient. Any dissemination, distribution or copying of the enclosed material is prohibited. If you receive this transmission in error, please notify us immediately by e-mail at abuse at rackspace.com and delete the original message. Your cooperation is appreciated.
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
>
>
> --
> Anne Gentle
> Rackspace
> Principal Engineer
> www.justwriteclick.com
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20151027/490231d3/attachment.html>
More information about the OpenStack-docs
mailing list