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

IPB

Welcome Guest ( Log In | Register )

3 Pages V   1 2 3 >  
Reply to this topicStart new topic
> 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
DavidFong
post Mar 25 2006, 10:30 PM
Post #2





Group: Members
Posts: 12
Joined: 9-April 04
Member No.: 2,754



Dear Jan,

I agree that the documentation on www.openzaurus.org, while containing many gems of information, is quite difficult to use.

For example, there no link on the main page to 'Documentation' or 'OpenEmbedded Wiki'/'Opie Wiki'/'GPE Wiki'. However there is a link to the bugzillas. a link for developers and then a link to this forum! Quite alarmingly, there is no main link on the main page describing how to install software, or describing what software is available.

Perhaps this is a symptom of OpenZaurus only recently moving from developer plaything, to something which is becoming slightly usable? Although I think GPE is not quite ready for the user...too many package conflicts...

Cheerio, David.
Go to the top of the page
 
+Quote Post
koen
post Mar 26 2006, 01:05 AM
Post #3





Group: Members
Posts: 1,014
Joined: 4-January 05
From: Enschede, The Netherlands
Member No.: 6,107



QUOTE(jan @ Mar 26 2006, 01:23 AM)
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.
*


A very VERY bad idea. Documentation for OpenZaurus belongs on openzaurus.org.
Go to the top of the page
 
+Quote Post
koen
post Mar 26 2006, 01:09 AM
Post #4





Group: Members
Posts: 1,014
Joined: 4-January 05
From: Enschede, The Netherlands
Member No.: 6,107



QUOTE(DavidFong @ Mar 26 2006, 06:30 AM)
Although I think GPE is not quite ready for the user...too many package conflicts...
*


I haven't seen any bugs filed for that <hint> <hint>

I propose a new rule: You can't whine about bugs if you haven't filed them in the bugtracker
Go to the top of the page
 
+Quote Post
lardman
post Mar 26 2006, 08:24 AM
Post #5





Group: Members
Posts: 4,515
Joined: 25-October 03
From: Bath, UK
Member No.: 464



You can add pages to wordpress on openzaurus.org afaik - you just need to get a password from hrw (things may have changed I suppose since I got mine).

If anyone fancies moving all of the pinned HowTo info to openzaurus.org then I'm all for it, I just don't have all that much time at the moment (though am happy to look though and check things).

Have a word with hrw about the layout of openzaurus.org if you think there should be a link to documentation on the front page (and links to the opie & gpe docs on handhelds.org ought to be added too).


Si
Go to the top of the page
 
+Quote Post
Hrw
post Mar 27 2006, 02:23 AM
Post #6





Group: Members
Posts: 1,376
Joined: 11-January 04
From: Poznań, Poland
Member No.: 1,413



Yep - documentation side of OpenZaurus sucks and we know it. Why it sucks? Mainly because OZ is made by developers (who heard about developers which like to write docs?).

We tried to get some documentation writers - I can provide accounts on openzaurus.org for anyone who want to work on it. I also plan to change few things on website:

- theme to 'In business' one -> http://www.hrw.one.pl/ as example
- adding wiki plugin for wordpress (not checked one yet)
Go to the top of the page
 
+Quote Post
obergix
post Mar 27 2006, 10:57 AM
Post #7





Group: Members
Posts: 128
Joined: 15-April 05
From: France
Member No.: 6,888



QUOTE(Hrw @ Mar 27 2006, 12:23 PM)
- adding wiki plugin for wordpress (not checked one yet)
*


Why not host a real wiki for openzaurus on openzaurus.org directly ? I'm not sure a wordpress plugin would do the job...

But I may be wrong;)

Definitely, the wiki is great because anyone can correct small problems instead of going through a whole workflow.
Go to the top of the page
 
+Quote Post
Hrw
post Mar 27 2006, 11:29 AM
Post #8





Group: Members
Posts: 1,376
Joined: 11-January 04
From: Poznań, Poland
Member No.: 1,413



Main problem with OpenZaurus website is hosting - it is hosted on sourceforge so no way to send mails from PHP which means that someone has to look from time to time and register people, mail them passwords etc - I tried to maintain that kind of setup few months ago with wordpress but finally disabled possibility to register.

And with all those spam problems on wiki we would need someone familiar with problem to maintain wiki - choosing good one, installing, maintaining users etc. I gave too much time for OpenZaurus in last months - need to stop it a bit and get some other things done. I need to get working SD/MMC card so I could test native SDK, probably will get irda keyboard for improving wireless keyboards support in OE derived distros, find funds for new wifi card as my dcf-660w too often switch to 1Mbps mode (I suspect breaks on circuit board level) - but those are OE/OZ related things.

I need to find some time to go to gym, spend more time with friends, read some books and do other things. Time to login into worst possible shell: Real Life.
Go to the top of the page
 
+Quote Post
obergix
post Mar 27 2006, 11:31 PM
Post #9





Group: Members
Posts: 128
Joined: 15-April 05
From: France
Member No.: 6,888



QUOTE(Hrw @ Mar 27 2006, 09:29 PM)
Main problem with OpenZaurus website is hosting - it is hosted on sourceforge so no way to send mails from PHP which means that someone has to look from time to time and register people, mail them passwords etc - I tried to maintain that kind of setup few months ago with wordpress but finally disabled possibility to register.
*


Speaking of that, I think that a bugtacker on its own wouldn't be so bad for openzaurus, maybe...

On the hosting thing, I think a dedicated *forge* may be interesting... maybe trac ?

Still it would need to be installed somewhere relyiably, and administered, yes...

No an easy issue.

My 2 cents.
Go to the top of the page
 
+Quote Post
h2gofast
post Mar 29 2006, 09:51 PM
Post #10





Group: Members
Posts: 33
Joined: 11-September 04
Member No.: 4,550



Is the interest in documentation for developers or users, because oz seems to be more of a developer community right now. There is always a need for user documentation, but is 3.5.4 mature enough that all a user needs is a good manual.
Go to the top of the page
 
+Quote Post
lardman
post Mar 30 2006, 02:29 AM
Post #11





Group: Members
Posts: 4,515
Joined: 25-October 03
From: Bath, UK
Member No.: 464



QUOTE
but is 3.5.4 mature enough that all a user needs is a good manual.


IMO, yes. And a good manual could make any complex process simple anyway wink.gif


Si
Go to the top of the page
 
+Quote Post
h2gofast
post Mar 30 2006, 10:23 PM
Post #12





Group: Members
Posts: 33
Joined: 11-September 04
Member No.: 4,550



QUOTE(lardman @ Mar 30 2006, 10:29 AM)
IMO, yes. And a good manual could make any complex process simple anyway wink.gif


Si
*


I agree but complex is a relative term. What an ubuntu user might find too complex to attempt, a gentoo user might find routine. I'm guessing the ideal manual would be able to bring an ubuntuan up to speed so that he would be able to get mplayer running on his zaurus without sym linking a couple of files and experimenting with a half a dozen command line flags before some video will run without crashing the zaurus.
I've used linux for years now and would like to return the favor. Finding a project that needs documentation would be ideal for me, because I don't code, but I can write, and I'm looking for a summer project.
Go to the top of the page
 
+Quote Post
CoreDump
post Mar 30 2006, 11:43 PM
Post #13





Group: Members
Posts: 715
Joined: 25-July 04
From: .de
Member No.: 4,094



QUOTE(h2gofast @ Mar 31 2006, 08:23 AM)
QUOTE(lardman @ Mar 30 2006, 10:29 AM)

IMO, yes. And a good manual could make any complex process simple anyway wink.gif


Si
*


I agree but complex is a relative term. What an ubuntu user might find too complex to attempt, a gentoo user might find routine. I'm guessing the ideal manual would be able to bring an ubuntuan up to speed so that he would be able to get mplayer running on his zaurus without sym linking a couple of files and experimenting with a half a dozen command line flags before some video will run without crashing the zaurus.


Speaking of which, mplayer in 3.5.4.1 is shipping with a default config and should now work out-of-the-box on all devices.
Go to the top of the page
 
+Quote Post
lardman
post Mar 31 2006, 02:17 AM
Post #14





Group: Members
Posts: 4,515
Joined: 25-October 03
From: Bath, UK
Member No.: 464



QUOTE
I agree but complex is a relative term. What an ubuntu user might find too complex to attempt, a gentoo user might find routine. I'm guessing the ideal manual would be able to bring an ubuntuan up to speed so that he would be able to get mplayer running on his zaurus without sym linking a couple of files and experimenting with a half a dozen command line flags before some video will run without crashing the zaurus.


I say aim low. An experienced user can always skim read to get to what they need to know.

QUOTE
I've used linux for years now and would like to return the favor. Finding a project that needs documentation would be ideal for me, because I don't code, but I can write, and I'm looking for a summer project.


Great! I should have more time over the summer so I'm happy to help you out with it all.

Si
Go to the top of the page
 
+Quote Post
lardman
post Mar 31 2006, 06:29 AM
Post #15





Group: Members
Posts: 4,515
Joined: 25-October 03
From: Bath, UK
Member No.: 464



Right, some movement has begun:

We have a number of HowTos on openzaurus.org, they can be found here:
http://openzaurus.org/wordpress/howto/

There's also a FAQ that needs to be filled in:
http://openzaurus.org/wordpress/faq/

Once we create some general purpose documentation pages they will also be linked from the top bar.

So people, contact hrw for a login and password and start adding HowTos (including the info from the pinned USB and Syncing threads), FAQ entries and general documentation.

Both hrw and I are contactable on IRC in #openzaurus for any queries.

Thanks,


Si
Go to the top of the page
 
+Quote Post

3 Pages V   1 2 3 >
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: 25th July 2014 - 11:08 PM