[maemo-community] The role of the docmaster

[From: Dave Neary]

Hi,

Thanks for starting the discussion, Quim. While I've felt that the 
things I've been working on have had value for the community, I've 
started feeling slightly uneasy about the increasingly inaccurate job 
title :)

Quim Gil wrote:
> But... what does this mean in practice? Some ideas to consider:
> 
> - There are many bugs about the official documentation. The stable and
> the unstable. What bugs are more important? What are more urgent? The
> docmaster can chase Maemo SW on the things that need a fix before the rest.
> 
> - Are the official docs delivered what the community needs? Maybe there
> is something important missing. Maybe there are some areas that should
> be documented further. The docmaster could influence the planning for
> future documentation work.

One of the difficulties areound official documentation to date has been 
what relationship, if any, is desired between the community and the 
Nokia docs team.

I get included on the CC list for docs announcements regularly, but I 
have not had the impression that any input was expected on my part. For 
the rest of the community, the docs creation process is even more 
opaque. In some sense, I've been in "wait & see" mode given the stated 
desire to have official docs hosted in a wiki - but even then there are 
myriad issues which I don't know the answer to - what will the reference 
documentation be, docbook or wiki? How will we handle documentation for 
different maemo versions? Is there any way to allow documentation 
co-creation with the community, when much of the new documentation is at 
least partially covered by confidentiality until platform releases?


> - What about the frequent questions from users and developers. Are they
> being followed to detect what needs more/better documentation, or just a
> prominent place somewhere so people can find it?

I remember your general position on FAQs from last year - if there is a 
need for a FAQ, then the existing documentation isn't good enough. The 
FAQ should be answered in the docs and be easy to find.

We haven't yet got a framework in place where questions & answers are 
made permanent. At what stage does a Q become a FAQ? The first time it's 
asked? The second or third? Do we need one FAQ, or one per use-case type 
(developer, user support, community)?

> - And the documentation tools. We have discussed about using the wiki
> for developer documentation, about publishing the APIs nicely à la
> library.gnome.org... what is the status of these projects? Is the doc
> master not only following them but active there?

I should work soon on recruiting and organising a group of editors for 
the wiki.

We already have the problem of name-space issues, inconsistent page 
naming, hairy page growth, and the mix of work pages (sprints), task 
definitions & tracking (Task:) and user or developer documentation which 
are making maintenance more complicated.

I plan on doing something serious about this issue before the end of the 
month, in connection with the slightly related issue of brainstorm 
maintenance.


> Then there are problems of documentation in the community projects e.g.
> 
> - Plenty of tips and tricks lost in talk.maemo.org. Who will recover them?

I admit that I am not active on Talk. I really like David's idea of 
WikiTalk to allow a forum user to wikify a forum thread, but I fear lots 
of things for which the wiki is not set up:
  * Not easy to merge 2 pages
  * Can't easily delete a page as a duplicate
  * Can't easily detect if someone already wikified a discussion
  * How do you get new pages linked usefully?

The only solution I can see to these problems right now is the mediawiki 
solution - have a big huge motivated wiki editing team which keeps the 
garden pruned. Last time we started this for the wiki migration, it 
worked well, but we ended up with only 2 or 3 active editors, which 
resulted in less active editing once teh initial impetus was done & the 
wiki was successfully migrated. We'd need to solve this problem again, 
and more permanently, this time.


> - Actually there was the debate of the old ITt wiki and the diff with
> still with the tmo wiki. The docmaster should drive the discussion there
> and put time to fix what needs more urgent fixing.
> http://talk.maemo.org/showthread.php?t=26503

Thanks for the link. I'll take a look.

In general, what are people's expectations? Should I be very active on 
Talk, following new threads & participating more? I did try to find a 
good RSS feed to subscribe to last year, but I found myself being 
drowned out by the number of new forum posts & couldn't easily follow 
the forum over RSS. I've since been working under the assumption that if 
there is a thread which is particularly interesting, it will get brought 
up on -communty, -developer or -users (all of which I'm subscribed to).

> - Also in Downloads there are many popular projects that are missing
> screenshots or a good description. The doc master could contact the
> remarkable projects and ask them to be a bit more careful about their
> releases.

OK - I don't mind doing this, but up until now I hadn't really 
considered it part of documentation.

> I'm not saying that Dave should all this all the time, but I think the
> docmaster should have the initiative to see what is most needed first
> and go for it. Some tasks are continuous and need to be made as part of
> as routine. Some others need a frontal attack until completed.
> 
> What will be the Must, Should and Could tasks of the docmaster in the
> following sprint?

Thanks for getting the discussion started Quim.

I definitely want more guidance on this as to what the priority items 
are - bearing in mind that many of the documentation tasks are ongoing, 
or it is unrealistic to expect completion in a month, we need to adapt 
them to fit into a sprint process - cut them into sub-tasks, for 
example. Of course I'm here to serve. The thread is timely also since 
now that we have deployed the new design for the site, I have been 
planning on consecrating more & more time to improving the organisation 
of the wiki.

Cheers,
Dave.

-- 
maemo.org docsmaster
Email: dneary at maemo.org
Jabber: bolsh at jabber.org