[dev] Manpage content

[Raymond Burkholder]

> I would prefer that we maintain 1 document that we can build man pages
> from, especially since the man pages are very neglected.  Having said that I
> totally see the need for a narrower man page that tells people how to get up
> and running.  Guess that is not a bunch of help.  Does anyone even use the
> man pages?

Kind of a chicken and egg problem?  No one uses them because they don't have current information?  Many might use them with updated information?  FRR may gain even more acceptance with more inclusive/documented details?

Can some options and commands be automatically extracted from source code?  I've had to go there to find interesting things.

Would it be acceptable to maybe point to some reference cumulus pages for information?  I've gone there as well for guidelines.

If I had time, I would extract and write stuff, but time eludes me.  Can't seem to figure out why.

Long man pages are good if they have lots of juicy tidbits of information.

Are links to blogs of useful value as a work around for lack of detail?  Although ... blog entries tend to become out-dated as code/commands evolves.

> On Wed, Jan 31, 2018 at 12:33 PM, Quentin Young
> <qlyoung at cumulusnetworks.com> wrote:
> > The only downside I see to option #2 is that some of the manpages have
> > small novels written inside them (for example the 24 paragraph section
> > on MED in the BGP chapter), which degrades their usefulness as the “quick reference”

Quick reference has its merits and detailed sections also have their merits.  Unless there are links to off-site links which can provide the background.  But detail should probably be local as there are typically FRR'isms in the interpretations which need to be mentioned.

The MED page is a good example of where we could be in some version of the future: details followed by command specifics.

> > people tend to use them for these days. Whereas the upside is 13 less
> > (albeit small) files to update when things change and a significant
> > increase in the amount of overall information in the manpages.

If, at some point, when someone is able to add detail, there may be much more than just 13 (albeit small) files.  How many sections might there be?  BGP could get quite large due to all the various ways it is/could be used: EVPN, MPLS, VNC, maps, lists, ....

Plus the various diagnostic commands which don't seem to be listed.

Should there be some thought to the future as to how sections could be arranged, and make some sort of notification somewhere of where users can go to add their own bits to the overall documentation project?  Wiki page or something?  It is probably dead easy for someone already familiar, but sometimes we need to be hand-lead to where we need to be.



-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.