OESF Portables Forum
Everything Else => Zaurus Distro Support and Discussion => Distros, Development, and Model Specific Forums => Archived Forums => Angstrom & OpenZaurus => Topic started by: jan 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 (https://www.oesf.org/index.php?title=Zaurus_How-To_Docs) or http://www.openzaurus.org/wordpress/ (http://www.openzaurus.org/wordpress/) or http://gpe.handhelds.org/documentation.phtml (http://gpe.handhelds.org/documentation.phtml) (for GPE) or http://opie.handhelds.org/cgi-bin/moin.cgi/OpieUserManual (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
-
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.
-
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.
[div align=\"right\"][a href=\"index.php?act=findpost&pid=120248\"][{POST_SNAPBACK}][/a][/div]
A very VERY bad idea. Documentation for OpenZaurus belongs on openzaurus.org.
-
Although I think GPE is not quite ready for the user...too many package conflicts...
[div align=\"right\"][a href=\"index.php?act=findpost&pid=120267\"][{POST_SNAPBACK}][/a][/div]
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
-
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
-
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/ (http://www.hrw.one.pl/) as example
- adding wiki plugin for wordpress (not checked one yet)
-
- adding wiki plugin for wordpress (not checked one yet)
[div align=\"right\"][a href=\"index.php?act=findpost&pid=120429\"][{POST_SNAPBACK}][/a][/div]
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.
-
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.
-
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.
[div align=\"right\"][a href=\"index.php?act=findpost&pid=120520\"][{POST_SNAPBACK}][/a][/div]
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.
-
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.
-
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
Si
-
IMO, yes. And a good manual could make any complex process simple anyway
Si
[div align=\"right\"][a href=\"index.php?act=findpost&pid=121034\"][{POST_SNAPBACK}][/a][/div]
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.
-
IMO, yes. And a good manual could make any complex process simple anyway
Si
[div align=\"right\"][a href=\"index.php?act=findpost&pid=121034\"][{POST_SNAPBACK}][/a][/div]
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.
-
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.
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
-
Right, some movement has begun:
We have a number of HowTos on openzaurus.org, they can be found here:
http://openzaurus.org/wordpress/howto/ (http://openzaurus.org/wordpress/howto/)
There's also a FAQ that needs to be filled in:
http://openzaurus.org/wordpress/faq/ (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
-
So people, contact hrw for a login and password
Lardman is also capable of adding users
-
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!
Si
-
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.
[div align=\"right\"][a href=\"index.php?act=findpost&pid=121244\"][{POST_SNAPBACK}][/a][/div]
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...
-
New OZ.org looks nice, but I agree with obergix. If you want user contributions we'll need something wiki like.
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...
[div align=\"right\"][a href=\"index.php?act=findpost&pid=121346\"][{POST_SNAPBACK}][/a][/div]
BTW: Can someone explain to me what OESF is and why you oppose using OESF wiki for OZ docs?
-
New OZ.org looks nice, but I agree with obergix. If you want user contributions we'll need something wiki like.
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...
[div align=\"right\"][a href=\"index.php?act=findpost&pid=121346\"][{POST_SNAPBACK}][/a][/div]
BTW: Can someone explain to me what OESF is and why you oppose using OESF wiki for OZ docs?
[div align=\"right\"][a href=\"index.php?act=findpost&pid=121413\"][{POST_SNAPBACK}][/a][/div]
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.
-
OpenZaurus documentation needs to be on the openzaurus site, not on some random other site.
[div align=\"right\"][a href=\"index.php?act=findpost&pid=121416\"][{POST_SNAPBACK}][/a][/div]
Fine, then setup a wiki on OZ.org
-
OpenZaurus documentation needs to be on the openzaurus site, not on some random other site.
[div align=\"right\"][{POST_SNAPBACK}][/a][/div] (http://index.php?act=findpost&pid=121416\")
Fine, then setup a wiki on OZ.org
[div align=\"right\"][a href=\"index.php?act=findpost&pid=121449\"][{POST_SNAPBACK}][/a][/div]
You could use the openembedded (the original one) wiki: [a href=\"http://oe.handhelds.org/cgi-bin/moin.cgi/OpenZaurus]http://oe.handhelds.org/cgi-bin/moin.cgi/OpenZaurus[/url] to host the intermediate content. When people are satisfied with it, they can move it to openzaurus.org
-
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
-
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?
[div align=\"right\"][{POST_SNAPBACK}][/a][/div]
(http://index.php?act=findpost&pid=121461\")
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 [a href=\"http://oe.handhelds.org/cgi-bin/moin.cgi/OpenZaurus]http://oe.handhelds.org/cgi-bin/moin.cgi/OpenZaurus[/url] ?
Then, hrw/lardman can give OZ.org WP accounts to most active wiki editors...
-
You can use OE Wiki - but please create pages like OpenZaurus/SomeThing, OpenZaurus/HowToDoIt etc.
-
You can use OE Wiki - but please create pages like OpenZaurus/SomeThing, OpenZaurus/HowToDoIt etc.
[div align=\"right\"][a href=\"index.php?act=findpost&pid=121559\"][{POST_SNAPBACK}][/a][/div]
Are going to encourage using OE Wiki OpenZaurs/whatever or will it be more a less ignored by everyone?
-
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
-
Would everyone (in this thread) agree to use and avocate http://oe.handhelds.org/cgi-bin/moin.cgi/OpenZaurus (http://oe.handhelds.org/cgi-bin/moin.cgi/OpenZaurus) ?
[div align=\"right\"][a href=\"index.php?act=findpost&pid=121504\"][{POST_SNAPBACK}][/a][/div]
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
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.
-
http://openzaurus.org/wordpress/2006/04/14/openzaurus-wiki/ (http://openzaurus.org/wordpress/2006/04/14/openzaurus-wiki/)
-
http://openzaurus.org/wordpress/2006/04/14/openzaurus-wiki/ (http://openzaurus.org/wordpress/2006/04/14/openzaurus-wiki/)
[div align=\"right\"][a href=\"index.php?act=findpost&pid=123185\"][{POST_SNAPBACK}][/a][/div]
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
-
http://openzaurus.org/wordpress/2006/04/14/openzaurus-wiki/ (http://openzaurus.org/wordpress/2006/04/14/openzaurus-wiki/)
[div align=\"right\"][a href=\"index.php?act=findpost&pid=123185\"][{POST_SNAPBACK}][/a][/div]
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
[div align=\"right\"][a href=\"index.php?act=findpost&pid=123186\"][{POST_SNAPBACK}][/a][/div]
Once again, OESF has *nothing* todo with OZ, so you'd need to copy the info
-
Right, I've done some editing of the installation instructions on the wiki: http://wiki.openzaurus.org/Install (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
-
lardman: repeated stuff can be resolved by using 'Template:' namespace - look in http://wiki.openzaurus.org/Help:Editing#Transclusion (http://wiki.openzaurus.org/Help:Editing#Transclusion)
And ReleaseNotes will contain only link to Install page - nothing more on installation.