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 <run...@gmail.com> wrote: > > On May 16, 2014, at 6:35 PM, Will Stevens <wstev...@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 <wstev...@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 <run...@gmail.com> wrote: > >> > >>> > >>> On May 12, 2014, at 4:29 PM, Will Stevens <wstev...@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 > >>> > >>> > >> > >
