[maemo-community] The role of the docmaster

[From: Quim Gil]

Hi,

ext Dave Neary wrote:
> 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.

What is desired is
http://wiki.maemo.org/Objective:Co-production_of_official_%26_community_documentation


> 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 

Wait & see will result in probably nothing compared to get involved and
help changing things. I'll give you the example of Andre, since is very
similar. He jumped on the internal error management processes, he got to
know the people responsible of them, he learned more about things that
are not as easy to change as it seemed initially... He combines a dose
of foot work (fight bug resolution after bug resolution) with more high
level tasks that help chan ging things (finding out the contacts behind
every component, producing weekly reports, all time statistics,
coordinating a Bugsquad team...

This way the day to day work helps him understanding the deeper
problems, and also the people that can help overcoming them. While
working hard and nailing down problems, he gets the recognition of
everybody so he becomes more influential and respected, also inside the
Maemo SW team.

The documentation bit is actually 10x simpler than the error management
stuff, if you want to jump and ride it.


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

It's you who should be pushing to get those answers.  :)  Define your
agenda with the community and push it to the people responsible of the
documentation processes in the Maemo SW team.

I can help you, as I help Andre, but it's you who needs to have the
initiative and the patience to deal with a busy but well-intentioned team.


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

Right. The FAQ represent bugs in the content of maemo.org. Developers
are conscious of the need of documentation and we can ask them to file
bugs (and they do that). Now maemo.org takes also care of end users, and
they are different beasts. They won't file bugs, they will ask the same
question missing an answer again and again (which is good).

Therefore, a FAQ becomes like a list of pending bugs to be fixed in the
maemo.org content. See the humble
http://wiki.maemo.org/Frequently_asked_questions based on frequent
questions in talk.maemo.org


> 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)?

You chase these answers.  :)


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

The idea is good. The implementation could be as simple as having a wiki
page to list Talk threads with content good enough to deserve to become
a more stable wiki page. There are not so many of those threads created
ever week, so I don't see the ned to made a code implementation in the
forum software itself.


> Last time we started this for the wiki migration, it 
> worked well, but we ended up with only 2 or 3 active editors,

I don't count many more regular contributors in the Bugsquad team, yet
they have made an amazing progress. Is mostly about being persistently
chasing a set of basic goals.

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

No, this doesn't happen. And actually these days there is much more
discussion and even good ideas and collaboration going on in tmo. This
doesn't mean you need to follow everything.

All maemo.org team members should follow the 'maemo.org' forum:
http://talk.maemo.org/forumdisplay.php?f=16

Then the 'Development' forum is a pure equivalent of maemo-developers
for those preferring forums to mailing lists.
http://talk.maemo.org/forumdisplay.php?f=13

And finally there is the 'Maemo 5' forum, placeholder of anything
related to Fremantle and that includes the first docs that were released
recently.
http://talk.maemo.org/forumdisplay.php?f=40

There is plenty more, but following the rest would be more of a hobby.
Each forum has its own feed.


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

It's not about you doing but about you bugging others to do it. If that
is in your scope or not, whatever the priorities are. It's maemo.org
content, and very visible now (top of the home).

-- 
Quim Gil
open source advocate
Maemo Software @ Nokia