Re: migrating the NetBSD users guide to the wiki

[Soren Jacobsen <snj%blef.org@localhost>]

On 05/07 17:45, Sevan Janiyan wrote:
> 
> 
> On 03/05/2019 22:16, Sevan Janiyan wrote:
> > 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?
> > 
> > Happy to do the other guides afterwards, at a later date.
> 
> I'm going to dogfood the for wiki for sometime (month or two) and see
> what's what, including updating the copy of the guide that and see
> what the pain point is over that period.

I don't think this is the way to go.  The issue is not pain, and it
never has been.  The Guide has been about as well-maintained as any of
our other non-base docs (including the wiki, which as you've recently
discovered, has plenty of stale or bogus content -- thanks for cleaning
that up, by the way!).  The issue is that writing documentation is not
glamorous and few people are excited to do it.

The htdocs/docbook version of the Guide has always been the
authoritative version.  It has been consistently maintained.  It offers
more flexible output in formats suited to a document of this nature.
Markdown is simpler to edit for simple documents, but the Guide is not a
simple document and docbook is well-suited to the task; markdown loses
its intuitive advantage as formatting complexity increases.  If people
are smart enough to find faults with the Guide's content (or have the
knowledge to provide new content), they are surely smart enough to be
able to handle DocBook.  It's not rocket science.

Deleting the htdocs version of the guide and switching to wikisrc serves
no purpose.  Keeping both is downright crazy.

Can we please just delete the wikisrc version?

Soren