Re: Hackathon: August 10th to 14th (documentation)

[Thomas Adam <thomas%xteddy.org@localhost>]

Hi,

[ Thanks for your efforts on this, it's refreshing to see. ]

On 26 July 2011 23:15, Julian Fagir <gnrp%komkon2.de@localhost> wrote:
> Hello,
>
> we will run the 15th NetBSD hackathon from August 10th to August 14th.

I've requested time off work especially for this; fingers crossed it's
approved.  :)  That way I plan to work hard on this hackathon for just
this purpose.

> The general topic is documentation. Though you can of course work on
> something else and just use the chance of some people gathered, I thought of
> four main topics to address:
>
>  1. Update and complete the several guides we have. The NetBSD guide could
>  have some updates (e.g. one could write about npf, or write one guide for it
>  on its own).
>  The internals guide has many XXXs in it, too, and the part about regression
>  testing is factually empty, and perhaps could need one guide on its own.

Flash support is a topic which comes up a lot on IRC, so if there's a
willing to address all possible solutions to a working flash player,
that'd be good; even if it include alternatives such as using clive,
youtube-dl, etc.

>  2. The wiki still needs some work on it. As was adressed in the prior
>  discussion, it's still difficult for users to participate in the wiki, they
>  need an OpenID, need to be activated as all their actions in it.
>  Additionally, the old wiki needs to be migrated completely into the new one.

This area is the one I am personally more interested in.  Note that I
originally instigated interest in this, and have to this day, a bunch
of HTML files converted from the so-called old wiki which might be of
some use still -- I'm trying to ask the powers that be (ahem, www@) to
check the status of my account, so I can upload these changes before
the hackathon begins, at least so they're there for people to work on
when it starts, etc.

Another question I have is the purpose of the wiki -- obviously the
wiki is easily able to add information to existing, static documents,
such as the NetBSD guide, etc., do we care and/or handle the case
where there's a potential over time for the wiki to grow information
which never makes it back into any more official/static information?
For example, I'm worried that there's the potential for overlap
between wiki pages springing into existence which contain useful
information, and for someone new to read the official static docs, and
never learn of the wiki's content which contains cool information.

How do we address that?  Because currently the wiki sticks out like a
sore thumb in that case; and maybe it should -- maybe that's the whole
point of the wiki, I don't know.  I'd welcome feedback from others,
but ideally some thought needs to be given as to how the wiki ties in
(if at all) to the existing static information that NetBSD churns out.

>  4. Minor improvements (working on manpages), thinkin about versioning the
>  documentation, address some topics that was not written about before.

Do you have examples where this is currently the case, or people have
requested documentation on?

Thanks again for this, Julian, it's much appreciated by me personally.

-- Thomas Adam

(I am "thomas_adam" on IRC on freenode, in case it matters; in the
usual NetBSD haunts already mentioned.)