Open Stack

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 12/07/15 15:10, Andreas Jaeger wrote:
> On 07/12/2015 01:48 AM, Anne Gentle wrote:
>>
>>
>> On Sat, Jul 11, 2015 at 2:35 PM, Andreas Jaeger <aj at suse.com
>> <mailto:aj at suse.com>> wrote:
>>
>>     On 07/11/2015 08:05 PM, Anne Gentle wrote:
>>
>>
>>
>>         On Sat, Jul 11, 2015 at 12:56 PM, Andreas Jaeger <aj at suse.com
>>         <mailto:aj at suse.com>
>>         <mailto:aj at suse.com <mailto:aj at suse.com>>> wrote:
>>
>>              So far, we have included RST files with
>>              :include: some-file.rst
>>
>>              and then added the file to a hidden toctree.
>>
>>              I propose - as mentioned by somebody else previously - to
>>         use the
>>              following practice:
>>
>>              * include files end with .txt
>>
>>              That's all. Since sphinx ignores .txt files, we do not need
>>         to add
>>              any hidden toctree at all...
>>
>>
>>         One potential benefit to keeping .rst is that they render okay
>> (not
>>         great, I know) on GitHub itself. Basically .txt files with RST
>>         markup
>>         don't render at all.
>>
>>
>>     With all these hidden tocentries, I consider inclusion of the RST
>>     some ugliness which we don't get with TXT files. It also makes it
>>     clear that TXT are included files.
>>
>>
>> Yep, I know what ugliness you mean. :)
>>
>>
>>
>>
>>         I've seen both practices so we should discuss, adopt one and
>>         stick with it.
>>         Thanks for bringing it up Andreas!
>>
>>
>>     Btw. since we do not have <section> but headings with specific
>>     markup for each level, an include file with headings might not be
>>     reused in other places - only if it's at the same level of headings.
>>
>>
>> By "might not be reused" do you mean should not be reused at all, or
>> only reused if all the headers in the file will be at the same heading
>> level in each inclusion?
> 
> Only reused if all the headers in the file will we at the same heading
> level in each inclusion. Meaning.
> 
> You cannot do:
> 
> Some header with second-level heading
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> :include:...
> 
> as well as:
> 
> Some other header with third-level-heading
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> :include:...
> 
> if your include file includes headers since include is a *verbatim*
> include and not a reference.
> 
>> I haven't studied the plans for the user guide/ admin guides re-works to
>> know if there will be much of this.
> 
> Just grep for ":hidden:" to find the hidden toc trees.
> admin-guide-cloud-rst currently has four of them and there are two in
> the install-guide-rst directory.
> 
>>
>>     Thus, my preference would even be to avoid includes *unless* we need
>>     them for duplicate content. But so far I haven't seen any buy-in on
>>     this, so propose the above.
>>
>>
>> So, best practice, stop duplicating content? Or avoid includes always?
> 
> My preference:
> Use tocdirs and reference the files from there, includes should be only
> used for duplicated content but not to split up large files. For
> splitting up large files, use a proper table of content. If a file is
> large in source, it will be large in HTML as well, so proper structuring
> needs to be thought about

A properly architected guide really shouldn't have particularly lengthy
files. Of course, that's an ideal world scenario, too. But suffice to
say that if a file is big enough to be unwieldy, then it's a trigger for
someone to take a look at how the information is being presented.

> 
> Includes should be only used for duplicated test that shows up in
> several places. I like how it's done in
> https://review.openstack.org/#/c/196890/ for the smaller files. I'm not
> sure about the 350 lines of duplication.
> 
>> I'd lean towards flatter less book-ish structures myself but I don't

I definitely agree with flatter structures where possible, but dislike
the idea of duplicating content where we can avoid it.

>> know how things are looking for the re-architecting. Looking at
>> http://specs.openstack.org/openstack/docs-specs/specs/liberty/reorganise-user-guides.html
>>
>> we may need to avoid includes?
> 
> I think we should use them for smaller duplicate text but not to split a
> large file into smaller ones.

+1

L


- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQEcBAEBAgAGBQJVohAzAAoJELppzVb4+KUy9hcH/1rsfLFFtlq4wsW6pclem5p3
PmHhQtUKTzrWWtBxi6WbBwBBQxoc8ElR1LV9osgZeXBWu01Rn2isv7x6NZ2qMvBT
ceBC0iMvWEysS9B8zU8FnMK0alNzg2QiR3oNI8IwP8hiONcZMxJz3K5Wq6Z9flh0
CnRlzOFkOSJ8pvKfC6LCAoqZhZhfjMdsAwNDqZ78Lew59vG1WYgwOFN5UpWEnyg9
/7rV5a6awtJcejKXViA9SVohrI60WTtnW+9q9hQ2HhYoNtltHy4Jrv+IbQV1gcf/
zJTe5IYYgZqOgAThGXEjyA4yF9xN2YUlT/2eivzO0C+mZga2vpk/y77/EwLopdI=
=X6Sj
-----END PGP SIGNATURE-----