Re: migrating the NetBSD users guide to the wiki

["J. Lewis Muir" <jlmuir%imca-cat.org@localhost>]

On 05/04, John Nemeth wrote:
> As for the vaunted "lower barrier", it is pretty much nonsense. nybody
> Athat can program in C can write/modify XML.

I agree that editing XML is not hard.  However, I would say that the
DocBook syntax is way more complicated than Markdown.  You can summarize
the Markdown syntax in a page that will fit on a typical computer
screen; not so with DocBook.  Of course, DocBook is able to express way
more than Markdown.  So, it depends what you're after.

Are you talking about existing NetBSD developers or anyone?  If you're
talking about anyone, then, regardless of the underlying document
format, I still think there's a lower barrier to entry for the NetBSD
Wiki than for the NetBSD Docs.  To see this, just enumerate the steps
required to make a typo fix for the two documents and see how long each
one takes.  The NetBSD Docs would get killed compared to the NetBSD Wiki
(if it worked right; more on that below).

Even better than a wiki, IMO, is documentation hosted on GitHub,
Bitbucket, or similar.  There the barrier to entry is really low if the
contributor already has an account on the hosting platform: in a web
browser, fork, make a typo fix in-line, and submit a pull request.  The
repo owner can review and press a button to merge.

If it's a more complex change, then yes, the contributor would likely
fork, download the repo, make the change, push to their fork, review
in a web browser, and then submit a pull request.  But even in this
workflow, the significant barrier of needing pkgsrc/meta-pkgs/netbsd-www
is eliminated compared to the NetBSD Docs.

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.  And that
could be fine.  I can even imagine a system where it would be pretty
accessible, though, such as something like GitHub but that supported
DocBook such that I could push a change to my fork and see it rendered
as HTML before submitting a pull request.  This would eliminate the need
for pkgsrc/meta-pkgs/netbsd-www.

> 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.

If you're talking about anyone, I don't think the above would tell you
much for two reasons:

1. Since the guide exists in two places,

     NetBSD Docs: https://wiki.netbsd.org/guide/index/

   and

     NetBSD Wiki: http://netbsd.org/docs/guide/en/

   , a person needs to figure out which version is the correct one to
   edit.  It seems that the NetBSD Docs version is the most recent and
   contains more information.  So, if anyone is going to contribute,
   they would likely settle on the NetBSD Docs version, not the NetBSD
   Wiki version, so NetBSD Wiki stats might not be very representative.

2. There's no easy way for anyone besides a NetBSD developer to
   contribute to the NetBSD Wiki.  At

     https://wiki.netbsd.org/

   there's a "How to edit" link to a page that says

     If you're not a NetBSD developer, you can add a comment to any
     page. We intend to develop some custom features for ikiwiki that'll
     provide more meaningful ways for you to participate. Until then,
     please bear with us and comment freely.

   So, someone who is not a NetBSD developer can't even contribute in
   the typical way for a wiki by editing the wiki directly.  That's a
   significant barrier to receiving contributions right there.

   And to make matters worse, in order to leave a comment, you have to
   log in with an OpenID, and that is not clear how to do.  (I reported
   this in misc/54021.)  So, it's likely that no one besides a NetBSD
   developer can even add a comment at the moment.  Given this, I would
   say there's a good chance that no one besides a NetBSD developer will
   contribute to the NetBSD Wiki at all.

Regards,

Lewis