[maemo-community] The role of the docmaster

[From: Dave Neary]

Hi,

Quim Gil wrote:
> 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

Just to be clear - I mean in both directions. I haven't felt any 
specific push from the community to write API docs or official 
tutorials, so I'm wondering if the maturity is there in the community to 
do effective co-production. Certainly, an important step towards true 
co-production is that the official documents be created in a publicly 
accessible system, with tools, norms and procedures all publicly 
available and documented.

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

Thanks for the suggestions.

I am having a little trouble seeing what the first step might be - what 
is the documentation equivalent of the bug tracking system? What is my 
equivalent of "fighting a bug resolution"?

I am definitely interested in better understanding the internal docs 
team process, and figuring out where we want to go and how we can start 
going there.

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

OK. Many of those questions simply don't have answers right now - others 
have answers which depend a lot on people other than me.

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

While the answer has charm, I don't think it's my role to impose 
practices either... in many cases, an answer exists that I'm not aware 
of in current practices, or someone else will have a better idea of an 
answer than me. My role is to condense what's currently happening into 
something coherent, not to decide project policy. Don't you think?


Anyway - let's start the job, and see how we get on.

I will try to find time this week to come up with a succinct description 
of the role of docmaster, and try to live up to it over the coming months.

Cheers,
Dave.


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