On Mon, 6 May 2019 11:03:35 -0500 "J. Lewis Muir" <jlm...@imca-cat.org> 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
