cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Will Stevens <wstev...@cloudops.com>
Subject Re: [DOCS] Using Includes in the Administration Guides
Date Fri, 16 May 2014 21:58:27 GMT
Here is a pull request for the changes I did today:
https://github.com/apache/cloudstack-docs-admin/pull/11

Let me know if you have questions.

Cheers,

Will


On Fri, May 16, 2014 at 5:12 PM, Will Stevens <wstevens@cloudops.com> wrote:

> Ok, I am almost done with the first pass on the networking section.
>
> I have been focusing mainly on:
>
> - Splitting each section out into into its own include file in a
> 'networking' folder so they can be moved around and such easier.
> - Removing the extra white space returns between the list characters and
> the first line of the list item.
> - Referencing the images locally in their include file rather than in the
> 'networking2.rst' file, so if we move the files around, their image
> references still work.
>
> I have not spent time on actually reworking the content yet because this
> has been a lot of work.
>
> I will have a pull request ready shortly.
>
> Will
>
> PS - Should I create an issue in Jira for this work and then associate the
> pull request with that issue or should I just do the pull request and let
> you know?
>
>
> On Fri, May 16, 2014 at 1:49 PM, sebgoa <runseb@gmail.com> wrote:
>
>>
>> On May 16, 2014, at 6:35 PM, Will Stevens <wstevens@cloudops.com> 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 <wstevens@cloudops.com
>> >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 <http://tools.ietf.org/html/rfc5517
>> >`_
>> >> 'managing_networks.rst' => Environment <
>> http://tools.ietf.org/html/rfc5517
>> >>> `__
>> >>
>> >> 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 <runseb@gmail.com> wrote:
>> >>
>> >>>
>> >>> On May 12, 2014, at 4:29 PM, Will Stevens <wstevens@cloudops.com>
>> 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
>> >>>
>> >>>
>> >>
>>
>>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message