Re: migrating the NetBSD users guide to the wiki

["James K. Lowden" <jklowden%schemamania.org@localhost>]

On Mon, 6 May 2019 11:03:35 -0500
"J. Lewis Muir" <jlmuir%imca-cat.org@localhost> wrote:

> Still, I appreciate the expressiveness of DocBook, and if it were
> decided to stick with it, I could see the value, but I think it's
> likely always going to have a higher barrier to entry than Markdown.  

The evidence is nil for the proposition that "barrier to entry"
materially discourages anyone from documenting anything.  I have yet to
see the project whose superior documentation is credited to the ease
with which it can be changed.  

On the contrary, simple documentation systems seem to lead inexorably
to sub-par documentation.   Markdown's own Fireball site is a prime
example.  

I don't have a dog in this fight, but would like to make one simple
observation that's evidently not obvious: mdoc (and/or maybe ms) is the
ideal documentation system for NetBSD.  

Why?  To edit almost any man page requires knowledge of mdoc.  The bulk
of NetBSD documentation is man pages.   By using mdoc for the Guide
etc., the project imposes the least on a contributor, i.e., the need to
learn one and only one documentation system.  

mdoc and ms are both more powerful and simpler than DocBook.  Just look
at the tag/macro count, the amount of markup, and the size of the
documentation for each system.  ms+mdoc is less than 100 pages; The
DocBook Definitive guide weighs in at over 500 pages.  

--jkl