Documentation Team. Consensus, votes, how YOUR OPINION COUNTS!

[Stroller]

On 24 Jul 2008, at 20:21, Justin Wong wrote:
> ...
> I must say, though, that with a team of any significant size, we'll
> unlikely be getting consensus on every matter. What happens then?

Votes!

This is not quite the same thing as consensus, but needs must.  
Ideally we make suggestions and they get modified by discussion and  
compromise into something we can all agree on (that IS consensus!).

There may be some stuff that we have to say to Michael & Brenda,  
"please go away and check with Openmoko management that this is OK"  
but for most everyday, "how do we organise pages which deal with this  
matter?" subjects we should be able to say "what do you think of  
this?" and get useful opinions.

For heck's sake! Most of the reorganisation and tidying that needs  
doing is OBVIOUS, and we're only dithering because we're each  
reluctant to be seen as assuming a "wild west" approach.

I think it's Linus who may have said that managing open-source  
contributors is like herding cats, but whatever, it's true! Things  
aren't going to get done for some "leader" who hands us chores we  
don't want to do. That would eventually, nay quickly, lead to  
volunteers leaving.

We have a dozen people listed on the "Wiki Maintainers" page. I think  
that's basically the volunteers from the original -comminity request  
for help. That means that everytime someone makes a proposal we take  
it seriously and at least half a dozen people say "yay" or "nay".
<rant> I'm sorry - I don't see what's so difficult about this. Why  
won't anyone talk to me?!?!?! </rant>

All it takes is us all being co-operative and respecting each other.  
If someone comes up with an idea, take the time to read it, consider  
it, and reply. When there's resounding approval the volunteer can get  
on with undertaking the task he's proposed; when there's disagreement  
we have to trust each other to have respect for the other team  
members' opinions, to wait and reconsider their suggestions.

Michael: you represent Openmoko here. Am I right here? Or waaaaay off- 
base? Who's the boss? Are you? Are we ALL the boss, together?

> I see quite a bit of work going into the wiki right now, but how does
> this work fit into the overall big picture plans to fix the
> documentation?  Is this bigger picture written down somewhere so wiki
> maintainers know what they're doing is right or is there currently
> only a list of "random" tasks to accomplish?

I think if  you look back over the posts of the last few days there  
may be a page (or several!) like that.

I don't personally see a great deal of benefit to arbitrary lists of  
stuff, because I don't see how they motivate people.

Tasks have to be interesting if we want volunteers to do them.

I am much more likely to check periodically a page which is  
automatically generated and which shows every page with a {{FIXME}}  
tag on it. This has the advantage of being easily contributed by  
regular users - they see something that needs contributing to the  
main wiki, type up a paragraph or two and see that an additional  
explanation would be useful. They have already added something useful  
to the wiki, but by simply adding {{FIXME:may be problematic if your  
router assigns eth0 an address in the 192.168.0.x range}} they enable  
anyone checking the FIXME category page to see an opportunity for  
their own contribution to improve the wiki and complete the work. All  
it needs is half a dozen people to say "yes, this is a good idea" and  
(following a few days for the implementation details) it'll get done.

> Example, how do we know we need a FAQ?
> Who is the FAQ targeted towards?

Well, this has been raised already. Same old problem: no answers  
(well, few of them).

I suppose we know we need an FAQ because some questions are  
frequently asked, and the point of an FAQ is to answer them once to  
save us having to do so repeatedly.

As such, I see the "Getting Started FAQ" [1] as being in the "true  
spirit" of FAQfulness. It consists of questions I have this week seen  
asked repeatedly on IRC and mailing lists. The current main FAQ is a  
big horrible & outdated mess, and I don't want to go near it with a  
dirty long stick. Nevertheless there are lots of questions which (I  
guess) are frequently asked, but which don't belong in the "getting  
started" category. "Can I use the Freerunner as my main phone?" is a  
good one.

I guess I personally see the main page as something we should "target  
towards" specific groups of people and the FAQ as, yes, a big fairly  
random collection of questions and answers, whatever happens to  
frequently come up.

As I say, right now the main FAQ is horrible, and I can't see that  
many of those questions really ARE frequently asked, not half as much  
as "Can I use the Freerunner as my main phone?" is. The questions  
"what is Openmoko?" and "what is the Freerunner?" are clearly  
distinct from "does the Freerunner have a camera?", "what GUI widgets  
can I run on Openmoko?" and "what GPS software runs on Openmoko?"  
Ferenc (I think) disapproves of multiple FAQs, so for the moment at  
least, we could break a main FAQ into sections (about us (??),  
hardware, software &c).

I hope you find these opinions useful,

Stroller.


[1] http://wiki.openmoko.org/wiki/Getting_Started_FAQ