OESF | ELSI | pdaXrom | OpenZaurus | Zaurus Themes | Community Links | Ibiblio

IPB

Welcome Guest ( Log In | Register )

> Shouldn't All Those Pinned Howto Posts Be On Wiki?, Lack of organization make us inefficient
jan
post Mar 25 2006, 05:23 PM
Post #1





Group: Members
Posts: 88
Joined: 10-February 06
Member No.: 9,115



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 http://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
Go to the top of the page
 
+Quote Post

Posts in this topic
jan   Shouldn't All Those Pinned Howto Posts Be On Wiki?   Mar 25 2006, 05:23 PM
DavidFong   Dear Jan, I agree that the documentation on www.o...   Mar 25 2006, 10:30 PM
koen   QUOTE(DavidFong @ Mar 26 2006, 06:30 AM)Altho...   Mar 26 2006, 01:09 AM
koen   QUOTE(jan @ Mar 26 2006, 01:23 AM)To make a l...   Mar 26 2006, 01:05 AM
lardman   You can add pages to wordpress on openzaurus.org a...   Mar 26 2006, 08:24 AM
Hrw   Yep - documentation side of OpenZaurus sucks and w...   Mar 27 2006, 02:23 AM
obergix   QUOTE(Hrw @ Mar 27 2006, 12:23 PM)- adding wi...   Mar 27 2006, 10:57 AM
Hrw   Main problem with OpenZaurus website is hosting - ...   Mar 27 2006, 11:29 AM
obergix   QUOTE(Hrw @ Mar 27 2006, 09:29 PM)Main proble...   Mar 27 2006, 11:31 PM
h2gofast   Is the interest in documentation for developers or...   Mar 29 2006, 09:51 PM
lardman   QUOTEbut is 3.5.4 mature enough that all a user ne...   Mar 30 2006, 02:29 AM
h2gofast   QUOTE(lardman @ Mar 30 2006, 10:29 AM)IMO, ye...   Mar 30 2006, 10:23 PM
CoreDump   QUOTE(h2gofast @ Mar 31 2006, 08:23 AM)QUOTE(...   Mar 30 2006, 11:43 PM
lardman   QUOTEI agree but complex is a relative term. What ...   Mar 31 2006, 02:17 AM
lardman   Right, some movement has begun: We have a number ...   Mar 31 2006, 06:29 AM
Hrw   QUOTE(lardman @ Mar 31 2006, 04:29 PM)So peop...   Mar 31 2006, 06:54 AM
obergix   QUOTE(lardman @ Mar 31 2006, 04:29 PM)Right, ...   Mar 31 2006, 11:23 PM
jan   New OZ.org looks nice, but I agree with obergix. I...   Apr 1 2006, 03:17 PM
koen   QUOTE(jan @ Apr 1 2006, 11:17 PM)New OZ.org l...   Apr 1 2006, 04:35 PM
obergix   QUOTE(koen @ Apr 2 2006, 02:35 AM)OpenZaurus ...   Apr 2 2006, 01:21 AM
koen   QUOTE(obergix @ Apr 2 2006, 09:21 AM)QUOTE(ko...   Apr 2 2006, 02:45 AM
lardman   QUOTELardman is also capable of adding users smile...   Mar 31 2006, 07:44 AM
lardman   QUOTEFine, then setup a wiki on OZ.org The wordpr...   Apr 2 2006, 06:12 AM
jan   QUOTE(lardman @ Apr 2 2006, 04:12 PM)QUOTEFin...   Apr 2 2006, 02:23 PM
obergix   QUOTE(jan @ Apr 3 2006, 12:23 AM)Would everyo...   Apr 4 2006, 01:25 AM
Hrw   You can use OE Wiki - but please create pages like...   Apr 2 2006, 10:37 PM
jan   QUOTE(Hrw @ Apr 3 2006, 08:37 AM)You can use ...   Apr 3 2006, 01:20 AM
lardman   By all means use the oe.handhelds.org wiki then on...   Apr 3 2006, 02:38 AM
Hrw   http://openzaurus.org/wordpress/2006/04/14/openzau...   Apr 14 2006, 05:30 AM
jan   QUOTE(Hrw @ Apr 14 2006, 03:30 PM)http://open...   Apr 14 2006, 05:45 AM
koen   QUOTE(jan @ Apr 14 2006, 01:45 PM)QUOTE(Hrw ...   Apr 14 2006, 06:03 AM
lardman   Right, I've done some editing of the installat...   Jun 18 2006, 08:04 AM
Hrw   lardman: repeated stuff can be resolved by using ...   Jun 18 2006, 09:53 AM


Reply to this topicStart new topic
1 User(s) are reading this topic (1 Guests and 0 Anonymous Users)
0 Members:

 



RSS Lo-Fi Version Time is now: 21st August 2014 - 02:12 AM