Open Stack

Good Saturday to everyone!

Thanks Andreas for opening this topic. And thanks much Meg for such a
detailed answer!

I agree with Meg here + another argument to have small children files that
are logical sub-sections of 1 chapter: it's much easier to review and merge
these in comparison with 200-300 lines' looong memoirs. I prefer files no
longer than 100-150 lines. But I will gladly hear out other ideas on this
matter.

Best
Lena

On Sat, Jun 20, 2015 at 3:00 PM, <openstack-docs-request at lists.openstack.org
> wrote:

> Send OpenStack-docs mailing list submissions to
>         openstack-docs at lists.openstack.org
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> or, via email, send a message with subject or body 'help' to
>         openstack-docs-request at lists.openstack.org
>
> You can reach the person managing the list at
>         openstack-docs-owner at lists.openstack.org
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of OpenStack-docs digest..."
>
>
> Today's Topics:
>
>    1. Re: RST conversion and file splits ? (Meg McRoberts)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Fri, 19 Jun 2015 20:59:19 +0000 (UTC)
> From: Meg McRoberts <dreidellhasa at yahoo.com>
> To: Andreas Jaeger <aj at suse.com>,
>         "openstack-docs at lists.openstack.org"
>         <openstack-docs at lists.openstack.org>
> Subject: Re: [OpenStack-docs] RST conversion and file splits ?
> Message-ID:
>         <1002285246.2547175.1434747559361.JavaMail.yahoo at mail.yahoo.com>
> Content-Type: text/plain; charset="utf-8"
>
> I do not thoroughly grok the intricacies of toctree --I just try to follow
> whatsomeone else does and hope it doesn't blow up on me ;-)
> However, it sounds like you are musing about issues of source file
> structureand I have been thinking about that a bit.? It sounds like you are
> thinking abouthaving one big file per "topic".? I have worked with people
> who argue that nodoc source file should have more than one heading in it --
> each subsectiongets its own file.? My own preferences fall somewhere in the
> middle, but findingthe "sweet spot" between the two is non-trivial.
> The great advantage of having smaller files is that different people can
> work ondifferent sections at the same time without causing horrific
> 6-way-merge scenarios.For example, in the new HA Guide, we have a topic
> about configuring the controllernode for high availability.? This has
> subtopics for pacemaker/corosync, mysql/galera, rabbitmq,
> HAProxy, keystone, et cetera.? The writers and reviewers for each of these
> subsectionsare often different people, so having those subtopics in
> different files that are includedin the larger topic file has definite
> advantages.
> I would advocate a less-flat directory structure for the source files.?
> Our current practiceseems to be to give a common "front-end" to all the
> subfiles for a topic, which causessome really long file names; for example:
> ???? controller-ha.rst???? controller-ha-pacemaker.rst????
> controller-ha-galera.rst???? controller-ha-rabbitmq.rst
> ???? controller-ha-haproxy.rst???? et cetera
> It also makes for a very cluttered source directory.? Things would be
> cleaner if we hadonly the controller-ha.rst file in the source directory,
> with a controller subdirectory thathad files named pacemaker.rst,
> galera.rst, rabbitmq.rst, haproxy.rst...
> As appropriate, the subdirectory might have a subdirectory.? For example,
> the galerasubtopic might have separate sections for MySQL and MariaDB and
> maybe anotherdatabase or two.? Different people might work on different
> database options, so havinga galera subdirectory with different files for
> the different database architectures makessense.
> On the other hand, the haproxy subtopic might have sections for install,
> configure, verify,launch.? I don't see much advantage in breaking those up
> into separate files, although Iknow some people who would advocate for that.
>
> In addition to breaking the files up for parallel development, well-chosen
> discrete files cansimplify restructuring the material -- rather than having
> to yank 75 lines of doc source fromone file and insert it into another, you
> can just move the inclusion line from one topic fileto another and voila!
> What does everyone else think?meg
>
>
>       From: Andreas Jaeger <aj at suse.com>
>  To: "openstack-docs at lists.openstack.org" <
> openstack-docs at lists.openstack.org>
>  Sent: Friday, June 19, 2015 11:40 AM
>  Subject: Re: [OpenStack-docs] RST conversion and file splits ?
>
> On 06/19/2015 02:36 PM, Andreas Jaeger wrote:
> > With DocBook, we had often included one file from another - and used
> > that included file only in a single place. So, there was no reason to do
> > it from an editors point of view, just splitting of content.
> >
> > Looking at https://review.openstack.org/#/c/192575/ I wonder what's the
> > right thing to do. The included file is not mentioned in a table of
> > contents and thus we normally use ":orphan:" but this does not work
> > here, so a hidden toctable is used.
> >
> > BUT why should we split this up in several files at all? If there's a
> > toc table used - or the file is used in several places -, splitting it
> > up is fine but just for inclusion I see no need for separate files.
> >
> > Or is there a preference for how large files are and how to split them
> up?
> >
> > Is there any guidance we want to follow for file splits like these?
> >
> > Looking at the :orphan:/hidden toctable constructs, I'm against file
> > splits and therefore ask to see whether we can reach some consensus that
> > I then follow in further reviews,
>
> Another example with the same problem:
>
>
> https://review.openstack.org/#/c/193518/2/doc/admin-guide-cloud-rst/source/blockstorage.rst
>
>
>
> Andreas
> --
> ? Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
> ? SUSE LINUX GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany
> ? ? GF: Felix Imend?rffer, Jane Smithard, Dilip Upmanyu, Graham Norton,
> ? ? ? ? HRB 21284 (AG N?rnberg)
> ? ? GPG fingerprint = 93A3 365E CE47 B889 DF7F? FED1 389A 563C C272 A126
>
>
> _______________________________________________
> 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/20150619/10e0cb74/attachment-0001.html
> >
>
> ------------------------------
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
> End of OpenStack-docs Digest, Vol 36, Issue 48
> **********************************************
>



-- 
Best regards,
Olena Logvinova,
Technical Writer | Mirantis, Kharkiv | 38, Lenin av., Kharkiv
ologvinova at mirantis.com | +380950903196
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150620/0af56f64/attachment.html>