cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebgoa <>
Subject Re: [DOCS] Using Includes in the Administration Guides
Date Fri, 16 May 2014 17:49:56 GMT

On May 16, 2014, at 6:35 PM, Will Stevens <> wrote:

> One other thing.  It appears that the docs are being wrapped so the lines
> are never longer than something like 75 chars or something like that.  What
> number is being used for this so I can make all the networking docs
> consistent as I work on this.  I think 80 chars is pretty standard, but we
> seem to be using something less than that, so I want to verify that unit if
> possible…

I don't recall using a specific length. the original .rst files were generated by the pandoc
tool, so it could be that there is a max length in there.

Feel free to make a call on this.

Regarding the networking* files:

The managing_network.rst file was in the install doc until recently. I did not like have duplicated
content, so I actually tried to separate the content between install and admin.
You are right that the two files look very similar, but I don't recall which one is the first
one, probably networking2 is the latest and you can use that one, and remove managing_networks.
Just make sure that you are not loosing any content.

Feel free to re-arrange the admin doc, improve the flow of the section, split the files etc.

I am going to work on the install doc mostly, and pdion891 is working on the RN.

> Thx,
> ws
> On Fri, May 16, 2014 at 11:02 AM, Will Stevens <>wrote:
>> The two docs that are currently referenced in the index.rst are
>> 'networking.rst' and 'networking2.rst'.  The file 'managing_networks.rst'
>> file seems to be almost identical to 'networking2.rst' other than having a
>> bit more detail in some places and there being changes in formatting.
>> Lots of things like this:
>> 'networking2.rst' => |add-ip-range.png|
>> 'managing_networks.rst' => |add-ip-range.png: adding an IP range to a
>> network.|
>> Or things like this:
>> 'networking2.rst' => Environment <>`_
>> 'managing_networks.rst' => Environment <
>>> `__
>> It is looking like one file is the predecessor of the other.  Since
>> 'networking2.rst' is the one that is linked in the 'index.rst' file, is
>> that the master version of that documentation and the one I should be
>> working from?
>> Thanks,
>> Will
>> On Tue, May 13, 2014 at 4:16 AM, sebgoa <> wrote:
>>> On May 12, 2014, at 4:29 PM, Will Stevens <> wrote:
>>>> Hi All,
>>>> I have been building documentation for the Palo Alto Networks firewall
>>>> integration which I would like to add to the Administration Guide.
>>>> I have currently built the Palo Alto integration doc as a stand alone
>>> doc,
>>>> but I will be tweaking it in order to include it in
>>>> the Administration Guide.
>>>> Looking at the Administration Guide, I am noticing that the 'Managing
>>>> Networks and Traffic' section is very long and a bit difficult to
>>> manage as
>>>> it is.
>>>> I am wondering if it makes sense to have a 'networking' folder and each
>>> of
>>>> the subsections in that section be broken out into its own file which is
>>>> then included into the 'networking2.rst' file.
>>>> I am willing to work on this if you agree that this will simplify the
>>>> management of this section of the documentation.
>>> +1
>>> The all networking section in the admin guide needs to be cleaned up,
>>> there are currently three files:
>>> -networking.rst
>>> -networking2.rst
>>> -managing_networks.rst
>>> these files may have duplication and need to be organized much better
>>> have at it
>>> -sebastien
>>>> Cheers,
>>>> Will

View raw message