Author Topic: Shouldn't All Those Pinned Howto Posts Be On Wiki?  (Read 51645 times)

jan

  • Jr. Member
  • **
  • Posts: 87
    • View Profile
    • http://www.spacezone.de/zaurus/articles/
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
« Last Edit: March 25, 2006, 08:24:35 pm by jan »

SL-C860 (Boxer), OZ 3.5.4.1 GPE 2.7
my blog

DavidFong

  • Newbie
  • *
  • Posts: 12
    • View Profile
    • http://www.users.bigpond.com/vkelim/
Shouldn't All Those Pinned Howto Posts Be On Wiki?
« Reply #1 on: March 26, 2006, 01:30:30 am »
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.
« Last Edit: March 26, 2006, 01:31:02 am by DavidFong »
David Fong, Ivanhoe, Australia.
Zaurus 5500 (OZ 3.5.4 Opie), SL-C3200 (Debian)
Athlon XP (SuSE 10.2), Fujitsu P1610 (SuSE 10.2)
Panasonic DMC-FZ10

koen

  • Hero Member
  • *****
  • Posts: 1008
    • View Profile
    • http://dominion.thruhere.net/koen/cms/
Shouldn't All Those Pinned Howto Posts Be On Wiki?
« Reply #2 on: March 26, 2006, 04:05:30 am »
Quote
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.
Forums are not bugtrackers!!! Smart questions
Ångström release team
iPAQ h2210, iPAQ h5550, iPAQ hx4700, Zaurus SL-C700, Nokia 770, all running some form of GPE
My blog

koen

  • Hero Member
  • *****
  • Posts: 1008
    • View Profile
    • http://dominion.thruhere.net/koen/cms/
Shouldn't All Those Pinned Howto Posts Be On Wiki?
« Reply #3 on: March 26, 2006, 04:09:09 am »
Quote
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
Forums are not bugtrackers!!! Smart questions
Ångström release team
iPAQ h2210, iPAQ h5550, iPAQ hx4700, Zaurus SL-C700, Nokia 770, all running some form of GPE
My blog

lardman

  • Hero Member
  • *****
  • Posts: 4512
    • View Profile
    • http://people.bath.ac.uk/enpsgp/Zaurus/
Shouldn't All Those Pinned Howto Posts Be On Wiki?
« Reply #4 on: March 26, 2006, 11:24:18 am »
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
C750 OZ3.5.4 (GPE, 2.6.x kernel)
SL5500 OZ3.5.4 (Opie)
Nokia 770
Serial GPS, WCF-12, Socket Ethernet & BT, Ratoc USB
WinXP, Mandriva

Hrw

  • Hero Member
  • *****
  • Posts: 1366
    • View Profile
Shouldn't All Those Pinned Howto Posts Be On Wiki?
« Reply #5 on: March 27, 2006, 05:23:34 am »
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)
OpenZaurus 3.5.4x Release Manager
OpenEmbedded, Ångström, Poky developer
My website

Misc embedded hardware.

obergix

  • Full Member
  • ***
  • Posts: 128
    • View Profile
    • http://www.olivierberger.com/weblog/
Shouldn't All Those Pinned Howto Posts Be On Wiki?
« Reply #6 on: March 27, 2006, 01:57:29 pm »
Quote
- 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.
Zaurus SL-C1000 - OpenZaurus 3.5.4.1-alpha1 w/ GPE image (some packages "custom made", compiled at home from bitbake+openembedded)

Hrw

  • Hero Member
  • *****
  • Posts: 1366
    • View Profile
Shouldn't All Those Pinned Howto Posts Be On Wiki?
« Reply #7 on: March 27, 2006, 02:29:55 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.

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.
OpenZaurus 3.5.4x Release Manager
OpenEmbedded, Ångström, Poky developer
My website

Misc embedded hardware.

obergix

  • Full Member
  • ***
  • Posts: 128
    • View Profile
    • http://www.olivierberger.com/weblog/
Shouldn't All Those Pinned Howto Posts Be On Wiki?
« Reply #8 on: March 28, 2006, 02:31:42 am »
Quote
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.
Zaurus SL-C1000 - OpenZaurus 3.5.4.1-alpha1 w/ GPE image (some packages "custom made", compiled at home from bitbake+openembedded)

h2gofast

  • Newbie
  • *
  • Posts: 33
    • View Profile
Shouldn't All Those Pinned Howto Posts Be On Wiki?
« Reply #9 on: March 30, 2006, 12:51:14 am »
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

  • Hero Member
  • *****
  • Posts: 4512
    • View Profile
    • http://people.bath.ac.uk/enpsgp/Zaurus/
Shouldn't All Those Pinned Howto Posts Be On Wiki?
« Reply #10 on: March 30, 2006, 05:29:03 am »
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


Si
« Last Edit: March 30, 2006, 05:29:17 am by lardman »
C750 OZ3.5.4 (GPE, 2.6.x kernel)
SL5500 OZ3.5.4 (Opie)
Nokia 770
Serial GPS, WCF-12, Socket Ethernet & BT, Ratoc USB
WinXP, Mandriva

h2gofast

  • Newbie
  • *
  • Posts: 33
    • View Profile
Shouldn't All Those Pinned Howto Posts Be On Wiki?
« Reply #11 on: March 31, 2006, 01:23:40 am »
Quote
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.

CoreDump

  • Hero Member
  • *****
  • Posts: 713
    • View Profile
    • http://www.hentges.net
Shouldn't All Those Pinned Howto Posts Be On Wiki?
« Reply #12 on: March 31, 2006, 02:43:57 am »
Quote
Quote
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.
Webmaster of hentges.net & Embedded Linux Developer.

lardman

  • Hero Member
  • *****
  • Posts: 4512
    • View Profile
    • http://people.bath.ac.uk/enpsgp/Zaurus/
Shouldn't All Those Pinned Howto Posts Be On Wiki?
« Reply #13 on: March 31, 2006, 05:17:27 am »
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
C750 OZ3.5.4 (GPE, 2.6.x kernel)
SL5500 OZ3.5.4 (Opie)
Nokia 770
Serial GPS, WCF-12, Socket Ethernet & BT, Ratoc USB
WinXP, Mandriva

lardman

  • Hero Member
  • *****
  • Posts: 4512
    • View Profile
    • http://people.bath.ac.uk/enpsgp/Zaurus/
Shouldn't All Those Pinned Howto Posts Be On Wiki?
« Reply #14 on: March 31, 2006, 09:29:55 am »
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
C750 OZ3.5.4 (GPE, 2.6.x kernel)
SL5500 OZ3.5.4 (Opie)
Nokia 770
Serial GPS, WCF-12, Socket Ethernet & BT, Ratoc USB
WinXP, Mandriva