Help - Search - Members - Calendar
Full Version: Shouldn't All Those Pinned Howto Posts Be On Wiki?
OESF Forums > Distros, Development, and Model Specific Forums > Distro Support and Discussion > Angstrom & OpenZaurus
jan
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
DavidFong
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.
koen
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.
koen
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
lardman
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
Hrw
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)
obergix
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.
Hrw
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.
obergix
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.
h2gofast
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.
lardman
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
h2gofast
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.
CoreDump
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.
lardman
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
lardman
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
Hrw
QUOTE(lardman @ Mar 31 2006, 04:29 PM)
So people, contact hrw for a login and password


Lardman is also capable of adding users smile.gif
lardman
QUOTE
Lardman is also capable of adding users smile.gif


Cheers for upgrading my rights hrw,

Everyone else: It isn't that I was trying to get out of doing work!

biggrin.gif


Si
obergix
QUOTE(lardman @ Mar 31 2006, 04:29 PM)
Right, some movement has begun:

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.

*


That's fine and well... but I keep saying that nothing will beat a wiki... unless there is a team with a clear path drawn for the documentation tasks where one can easily know what to document, when and where...

Unless these requirements are met, I think a wiki is necessary...
jan
New OZ.org looks nice, but I agree with obergix. If you want user contributions we'll need something wiki like.

QUOTE(obergix @ Apr 1 2006, 09:23 AM)
That's fine and well... but I keep saying that nothing will beat a wiki... unless there is a team with a clear path drawn for the documentation tasks where one can easily know what to document, when and where...

Unless these requirements are met, I think a wiki is necessary...
*


BTW: Can someone explain to me what OESF is and why you oppose using OESF wiki for OZ docs?
koen
QUOTE(jan @ Apr 1 2006, 11:17 PM)
New OZ.org looks nice, but I agree with obergix. If you want user contributions we'll need something wiki like.

QUOTE(obergix @ Apr 1 2006, 09:23 AM)
That's fine and well... but I keep saying that nothing will beat a wiki... unless there is a team with a clear path drawn for the documentation tasks where one can easily know what to document, when and where...

Unless these requirements are met, I think a wiki is necessary...
*


BTW: Can someone explain to me what OESF is and why you oppose using OESF wiki for OZ docs?
*



OESF is a bad attempt at stealing the OpenEmbedded name and has nothing to do with OpenZaurus. OpenZaurus documentation needs to be on the openzaurus site, not on some random other site.
obergix
QUOTE(koen @ Apr 2 2006, 02:35 AM)
OpenZaurus documentation needs to be on the openzaurus site, not on some random other site.
*


Fine, then setup a wiki on OZ.org wink.gif
koen
QUOTE(obergix @ Apr 2 2006, 09:21 AM)
QUOTE(koen @ Apr 2 2006, 02:35 AM)
OpenZaurus documentation needs to be on the openzaurus site, not on some random other site.
*


Fine, then setup a wiki on OZ.org wink.gif
*



You could use the openembedded (the original one) wiki: http://oe.handhelds.org/cgi-bin/moin.cgi/OpenZaurus to host the intermediate content. When people are satisfied with it, they can move it to openzaurus.org
lardman
QUOTE
Fine, then setup a wiki on OZ.org


The wordpress is effectively a wiki, just one that requires username + password access.

Is that such a problem?


Si
jan
QUOTE(lardman @ Apr 2 2006, 04:12 PM)
QUOTE
Fine, then setup a wiki on OZ.org

The wordpress is effectively a wiki, just one that requires username + password access.

Is that such a problem?
*



Not at all. If you and hrw and whoever cares about OZ.org don't mind giving everyone access, preferably by a simple procedure which doesn't require manual work for you each time someone wants to do something.

The problem I see with the OZ.org WP attempt is that it looks official (written or approved by the developers). I trust OZ.org more than a OESF wiki. But if you are willing to be editor, why not?

Would everyone (in this thread) agree to use and avocate http://oe.handhelds.org/cgi-bin/moin.cgi/OpenZaurus ?
Then, hrw/lardman can give OZ.org WP accounts to most active wiki editors...
Hrw
You can use OE Wiki - but please create pages like OpenZaurus/SomeThing, OpenZaurus/HowToDoIt etc.
jan
QUOTE(Hrw @ Apr 3 2006, 08:37 AM)
You can use OE Wiki - but please create pages like OpenZaurus/SomeThing, OpenZaurus/HowToDoIt etc.
*


Are going to encourage using OE Wiki OpenZaurs/whatever or will it be more a less ignored by everyone?
lardman
By all means use the oe.handhelds.org wiki then once the docs are in a useful state they can be brought across to openzaurus.org (I'm happy to do that).


Si
obergix
QUOTE(jan @ Apr 3 2006, 12:23 AM)
Would everyone (in this thread) agree to use and avocate http://oe.handhelds.org/cgi-bin/moin.cgi/OpenZaurus ?
*


just a small remark : it won't help users understand the distinction between OE and OZ... I see lots of complaints on mailing lists or wiki about people not asking the right place... and fear it won't help in this respect wink.gif

Other than that, no objection... I've already added some content into OE"s wiki myself, and I understand the hassle with setting-up a dedicated OZ wiki.
jan
QUOTE(Hrw @ Apr 14 2006, 03:30 PM)


Great. Now we need to agree on which info is supposed te be on which wiki/site. There is already information about hardware on OESF wiki and about the GUIs on their respective wikis on handhelds.org. Link from OZ wiki or copy to OZ wiki? I prefer link.

Jan
koen
QUOTE(jan @ Apr 14 2006, 01:45 PM)
QUOTE(Hrw @ Apr 14 2006, 03:30 PM)


Great. Now we need to agree on which info is supposed te be on which wiki/site. There is already information about hardware on OESF wiki and about the GUIs on their respective wikis on handhelds.org. Link from OZ wiki or copy to OZ wiki? I prefer link.

Jan
*



Once again, OESF has *nothing* todo with OZ, so you'd need to copy the info
lardman
Right, I've done some editing of the installation instructions on the wiki: http://wiki.openzaurus.org/Install

Mainly just to try to clean them up and make them all reasonably similar in structure.

Ideally, I'd like them to all turn out something like the c7x0 one (though I still need to go through and check the grammar, etc.)

Obviously some require more details - collie (zImage memory split choices, poodle - pxa version for kernel, spitz - HDD stuff, so it's different), but hopefully this will all fit in okay.

Anyone have any comments about the structure I've put in (not on the poodle and spitz though as ran out of time)?

I'd prefer to not have links to release notes in the installation howtos for each machine, mainly because this will make maintaining them more time consuming, though they could be placed in a specific section at the end I suppose.

I also think that the specifics of formatting and accessing CF cards probably doesn't need to be repeated (this would be a good one to move to a separate page).

I'm not fond of adding links in to describe (re-)naming and use of the updater.sh, initrd.bin and zImage(.bin) files - firstly because this then means that the single page doesn't do the whole job (so it can't be printed out and used) and also because the functionality and naming may differ between machines.

Any thoughts?


Si
Hrw
lardman: repeated stuff can be resolved by using 'Template:' namespace - look in http://wiki.openzaurus.org/Help:Editing#Transclusion

And ReleaseNotes will contain only link to Install page - nothing more on installation.
This is a "lo-fi" version of our main content. To view the full version with more information, formatting and images, please click here.
Invision Power Board © 2001-2014 Invision Power Services, Inc.