Show Posts
16
Angstrom & OpenZaurus / Shouldn't All Those Pinned Howto Posts Be On Wiki?
« on: March 25, 2006, 08:23:36 pm »
OK. I'm not going to write another complaint about missing documentation. But -- let's face it:
* The pinned thread "OZ documentaion project" is dead, the link in post#1 is broken
* Most people seem to ignore the OESF wiki
* Those HOWTO articles don't really make good documentation. They're rather a list of "works for me" posts interrupted by questions with non-answers like "I'm not going to answer this here because this thread is not for questions".
* Things aren't stable here (as in debian stable). While it's great to get new software versions, along comes need for updated documentation.
* Most users are puzzled about where to look for info / ask questions because there are so many projects (OZ, OE, OPIE, GPE, upstream). This complexity is natural but provokes question in the wrong place. (The users usually get quickly answers here usually by on of the core developers, which is very nice but couldn't that time be used better?)
I wondered why people don't use the wiki much more. I know there are/were spam issues and thoughts about changing the software but the Wiki is still a good starting point, isn't it?
The wiki's content has some problems, too: Pages aren't always easy to find because too few other pages point there. Even worse, many pages have wrong names like "General" where it should "Networking via USB (General)" or "usbnet/general". Another big problem, most pages fail to say which software setup on the Z is required to make it work or the page names model and ROM version while it could actually be generalized. But, we can solve this. I think, when there's more attention on the wiki, it will be solved automatically. I'll help.
To make a long story short, I'd like to advocate something: Don't use OESF Forum for documentation, use the Wiki instead. I think, it won't be any more work in the short run and less in the long run.
Users or people asking questions:
* Whenever you have a question, check whether it's mentionend in https://www.oesf.org/index.php?title=Zaurus_How-To_Docs or http://www.openzaurus.org/wordpress/ or http://gpe.handhelds.org/documentation.phtml (for GPE) or http://opie.handhelds.org/cgi-bin/moin.cgi/OpieUserManual (for OPIE)
* When it was hard to find, add a link in a prominent place. If it was unclear, clearify.
* When it wasn't there and you solved it by searching the web or asking here or debugging, don't just tell the readers of OESF forum or your blog; tell everyone by contributing to (at least one of) the wikis. That way the knowledge is less volatile but can be updated when neccessary.
Everyone
* Distinguish between
1) general questions (stuff that you would expect in a HOWTO or FAQ) and
2) user specific problems (stuff that you would rather expect on a mailing list) when asking/answering questions. This is not trivial, but it helps a lot.
Developers or people answering questions:
* Distinguish the following cases
a) I know exactly what the problem is or
B) I have an idea about to howto fix / work around it.
* If B), say so. If successful and you have good faith that it wasn't only because of good luck, proceed, otherwise goto #.
* If 2) try to find out whether it can be tracked down to a general problem. If yes, proceed, otherwise goto #.
* Make sure good documentation exists.
* Don't answer the question, give a pointer to good documentation.
# Ask the user to write about the solution which worked for him.
These are just some thoughts I wrote at 3am (summer time, actually 2am). Share your ideas. I don't want to tell others how to do things. The imperatives above aren't rules just suggestions.
jan
* The pinned thread "OZ documentaion project" is dead, the link in post#1 is broken
* Most people seem to ignore the OESF wiki
* Those HOWTO articles don't really make good documentation. They're rather a list of "works for me" posts interrupted by questions with non-answers like "I'm not going to answer this here because this thread is not for questions".
* Things aren't stable here (as in debian stable). While it's great to get new software versions, along comes need for updated documentation.
* Most users are puzzled about where to look for info / ask questions because there are so many projects (OZ, OE, OPIE, GPE, upstream). This complexity is natural but provokes question in the wrong place. (The users usually get quickly answers here usually by on of the core developers, which is very nice but couldn't that time be used better?)
I wondered why people don't use the wiki much more. I know there are/were spam issues and thoughts about changing the software but the Wiki is still a good starting point, isn't it?
The wiki's content has some problems, too: Pages aren't always easy to find because too few other pages point there. Even worse, many pages have wrong names like "General" where it should "Networking via USB (General)" or "usbnet/general". Another big problem, most pages fail to say which software setup on the Z is required to make it work or the page names model and ROM version while it could actually be generalized. But, we can solve this. I think, when there's more attention on the wiki, it will be solved automatically. I'll help.
To make a long story short, I'd like to advocate something: Don't use OESF Forum for documentation, use the Wiki instead. I think, it won't be any more work in the short run and less in the long run.
Users or people asking questions:
* Whenever you have a question, check whether it's mentionend in https://www.oesf.org/index.php?title=Zaurus_How-To_Docs or http://www.openzaurus.org/wordpress/ or http://gpe.handhelds.org/documentation.phtml (for GPE) or http://opie.handhelds.org/cgi-bin/moin.cgi/OpieUserManual (for OPIE)
* When it was hard to find, add a link in a prominent place. If it was unclear, clearify.
* When it wasn't there and you solved it by searching the web or asking here or debugging, don't just tell the readers of OESF forum or your blog; tell everyone by contributing to (at least one of) the wikis. That way the knowledge is less volatile but can be updated when neccessary.
Everyone
* Distinguish between
1) general questions (stuff that you would expect in a HOWTO or FAQ) and
2) user specific problems (stuff that you would rather expect on a mailing list) when asking/answering questions. This is not trivial, but it helps a lot.
Developers or people answering questions:
* Distinguish the following cases
a) I know exactly what the problem is or
B) I have an idea about to howto fix / work around it.
* If B), say so. If successful and you have good faith that it wasn't only because of good luck, proceed, otherwise goto #.
* If 2) try to find out whether it can be tracked down to a general problem. If yes, proceed, otherwise goto #.
* Make sure good documentation exists.
* Don't answer the question, give a pointer to good documentation.
# Ask the user to write about the solution which worked for him.
These are just some thoughts I wrote at 3am (summer time, actually 2am). Share your ideas. I don't want to tell others how to do things. The imperatives above aren't rules just suggestions.
jan