Re: migrating the NetBSD users guide to the wiki

[John Nemeth <jnemeth%cue.bc.ca@localhost>]

On May 3, 10:16pm, Sevan Janiyan wrote:
}
} I've been trying to tidy up the wiki to cull old or duplicate content
} which we inherited from wiki.netbsd.se with the intention of adding
} useful info to the NetBSD guide and with that rejuvenating some of the
} content there before bringing the guide back to the wiki.
} 
} I stumbled across a copy of the guide in the wikisrc already which I'd
} not noticed before as I'd been mostly looking at the tutorials
} directory. The end result of the wikified version seems ok, what we lose
} in the power of docbook we gain in lower barrier to entry for contributions.
} 
} docbook
} pros: multi format output, pro authoring platform for writing books
} cons: xml, pkgsrc/meta-pkgs/netbsd-www dependency list
} 
} wiki
} pros: simple format (markdown)
} cons: no multi format output
} 
} I was wondering if I did the work to reconvert (resync?) the NetBSD
} guide from docbook to the wiki, could we delete the docbook version?

     Personally, I think the idea of migrating the guide to the
wiki is absolutely terrible.  The guide is intended to be printable.
This pretty much makes the "pro authoring platform" a necessity.

Also, in many ways, I would not call markdown a "simple format".
It uses punctuation and spacing as formatting info.  It is not at
all clear to a casual observer what the output for a given input
would be.  In comparison, XML is relatively easy to read, i.e. if
you see something like <ulink ...> you can reasonably guess that
it is a link of some kind, but in markdown when you see [xxx](yyy),
it can be hard to guess what that is (if "yyy" is a URL then it is
obvious, but otherwise it isn't).

     As for the vaunted "lower barrier", it is pretty much nonsense.
Anybody that can program in C can write/modify XML.  It really
isn't that difficult and we have lots of examples.  Also, one of
the major selling points for getting the wiki is that more people
would contribute due to the ease of doing so.  My prediction at
the time was that this wouldn't matter as coders are notorious for
not writing documentation.  I believe that my prediction has been
proven as there are very few people actively contributing to the
wiki.  As an aside, since I am curious about this, if I can get my
hands on the data, I'll try to run some stats on contributors.

} Happy to do the other guides afterwards, at a later date.
} 
}-- End of excerpt from Sevan Janiyan