The Documentation Apocalypse

[dansawyer]

One more for the WIKI-

Yes, wiki' s may be uneven. However they are wide bandpass and quick. After participating in this forum for several months now I would put forth that the the major roadblocks to new users as we move forward are:

1. Overview and howtos (there are several but realtively static)

2. New issues, new features, and new release notes

I would suggest we create a WIKI to address both of these. Once the first part is close to ocntent complete, i.e. the change rate slows, then that content may be moved to more perminent structure.

The second part remains open.

Again, I am willing to participate in the content creation.

Dan

[carpman]

Windrose, it is gratifying to see your intrest in documenting OZ. Since you seem so vocal about the problem, I'm sure you would have no problem in organizing this project, correct?

[zenyatta]

I reckon do the incubation here (as we all have access) then move it across once it's more complete.

I don't know if you've noticed, we don't actually have access - the ZUG wiki is locked down at the moment due to a vandalism incident some time ago. I believe offroadgeek will provide access details upon request via a private message but for your ordinary person, the wiki is read-only, and it is uncertain when that will change. I am in favour of using OE wiki since it is immediately available.

carpman: I detect a hint of sarcasm in your post (if I'm wrong please ignore this paragraph). It is understandable but a bit out of place, I think. Windriver has already made a great contribution by opening this topic and raising some valid points. Should he/she choose to get more involved, I'd be as thrilled as anyone but the fact is Windriver doesn't owe anything to anyone.

[lardman]

I am in favour of using OE wiki since it is immediately available.

I suppose so, I'm just not sure how happy the OE people will be about this (as it's supposed to be OE only - despite the OZ stuff on there).

the ZUG wiki is locked down at the moment due to a vandalism incident some time ago.

I didn't realise. What happened?


Si

[zenyatta]

Apparently, someone deleted a substantial part of the Wiki and offroadgeek had to restore it from backups, with some edits getting lost in the process. There was a discussion somewhere in the site-related forums on how to deal with such things but I don't know the conclusions.

As for the OE wiki, I wonder whether there is some OE person we can ask about it. It would be a temporary solution anyway (hopefully either ZUG or OZ.org will be sorted out within a few months) and I doubt we will be so prolific as to unduly burden the OE.org storage capacities.

[amrein]

Well, offroadgeek will have to use something like the ZUG password. In his post, he asked for help. I don't know if anyone answer to him. If I knew enough those kind of tools...

https://www.oesf.org/forums/inde...?showtopic=6926

[lardman]

Right, I've just emailed Rich Simpson, who's taken over the OZ.org site, to enquire as to when the wiki might be up and running. I'd prefer to do it all there if possible. That said, I've no idea if I'd even be given write access - I'm not a core developer, I steer clear of the mailing list and IRC, etc.

I note that there is already some stuff on the OE wiki; I must admit that I'm loath to alter stuff on there (though for this plan it would have to be re-structured, etc.), not quite sure why (probably because I've not had much to do with OE and the wiki other than using the software to build packages).

I don't know, but I think it would be a shame to have two sets of people working on the same thing at the same time.


Si

P.S. Perhaps I'm just being pessimistic

[Windrose]

dansawyer: I would put forth that the the major roadblocks to new users as we move forward are:
1. Overview and howtos (there are several but realtively static)
2. New issues, new features, and new release notes  I would suggest we create a WIKI to address both of these. Once the first part is close to ocntent complete, i.e. the change rate slows, then that content may be moved to more perminent structure.

Yes, that makes sense. If the goal is to make the OZ rom and OE GUI (or that X Window thingee, for that matter) easily accessible to the non-geek Zaurus user (let's just accept the debatable proposition that that is a non-empty set for the sake of argument), then I think the idea would be to organize it as some sort of a roadmap. Something maybe like:
1. How to completely back-up your existing system in case of disaster.
2. How to obtain and flash the OZ rom (by platform)(and how to decide on the GUI, perhaps)
3. How to pick and install new apps.
4. How to upgrade
5. Interesting facts you really ought to know

As dansawyer says, there really is a lot of this stuff extant. It maybe needs reorganizing and proofreading and some elaborations for the innocent user. As for example, I think it would be well at each stage to include a digression on What Could Go Wrong and Why. Partially to provide full disclosure and partially so the Befuddled User {Tm} can realize that others have encountered this problem and that (one hopes) there is a solution.

lardman: I note that there is already some stuff on the OE wiki; I must admit that I'm loath to alter stuff on there (though for this plan it would have to be re-structured, etc.), not quite sure why (probably because I've not had much to do with OE and the wiki other than using the software to build packages).

WRT OPIE, that manual is underway but kind of half-baked. Perhaps the thing to do is to lift the appropriate parts, rewrite as necessary, and footnote the section with credit and a link to the original?

carpman: Windrose, it is gratifying to see your interest in documenting OZ. Since you seem so vocal about the problem, I'm sure you would have no problem in organizing this project, correct?

I'll be happy to help where I can -- I do a better than fair impression of a Befuddled User.  My organizational skills are perhaps a trifle scant.

zenyatta: Just out of curiosity: is some of your work accessible on the Web?

Hell, who's isn't? But I doubt you'd find it particularly edifying. I mean, I'm not Neal Stephenson. I do science writing and public relations sort of work for one of the Federal labs. Newsletter items and such. In situ controlled growth of zinc-oxide nanowires on sapphire substrates, and similar chart-burners.

Windrose

[amrein]

The last time I checked, OE wiki was completely open to any change so I added a few lines without having to use a password.

I guess:

_ General FAQ / general Wiki on www.zaurususergroup.com
_ OZ or OE FAQ / specific Wiki on www.openzaurus.org or www.openembedded.org
_ pdaXrom FAQ / specific Wiki on www.pdaXrom.org

pdaXrom guys won't like to contribute specific pdaXrom entries anywhere else then pdaXrom.org for clarity and easy info search. Same thing for OE / OZ. Why should they? Rely on another website for your specific data? Bad idea. Make publicity in the competiror camp (why not?).

Twiki is an interesting engine. Zaurususergroup.com Wiki will certainly come back to read/write mode if someone help offroadgeek. A few wiki subjets will overlap with other wiki page thought but that doesn't matter. And all this... only if people have something to share on wiki.

btw, why bother? Forums are already split for clarity. Wiki too. Applications list on future http://www.killefiz.de/zaurus/ will be able to show packages for each distribution. There are only two open source OS competitors for the Zaurus at present so the real game can begin. OE/OZ guys know where they can contribute. pdaXrom guys know where they can contribute. Perhaps Debian users also know where to contribute.

Finally, the good question could be: does all generous guys who would like to help those projects know what they can do, where they should go, what they should use or what they should read? Can they find easily how they can contribute? Project like this have to think about the contributors flow. To give a good picture of the problem: we are lemmings!!! We are like lemming and if we don't know what to do we just walk and never stop walking. If no one know how to use our ability or how to control our flow then you lost the game (we fall in closed source trap, or we burn our money on other device, or we drown in a lot of documentations, or we bounce on closed open source projects and get back were we come from before coming back again... and so on).

(strange... there is no trolls today. Where are the great people with personal questions to change the thread subject or the two/three guys just trying to deny the obvious fact and more... ?)

[jamesm]

Like all good open source projects, an OZ documentation effort needs a group dedicated to guiding it in the right direction. Without some kind of formal 'overseeing-body' I feel this effort may go the way of many Wikis, not least the OE wiki which, although functional for people who know what they're doing, leaves much to be desired for the new user.

I feel fairly confident that several of the people who care enough to have posted here would shoulder some of the responsibility.

I personally would be happy to collaborate with you all in this effort. There you are, my neck is officially on the line, feel free to join me.

[Shdwdrgn]

I would certainly like to help out with documentation.  Since I reflash my Z so infrequently, I always feel like a total newbie, which is a great place to be in this case, since I won't take anything for granted.  And since I work on a helpdesk, I have a huge amount of experience at explaining things in layman terms.

Too bad I didn't take notes this week after flashing to OZ3.5.1/opie.  But I'm planning on trying out gpe later this week, so I'll see what I can document from that point.

[lardman]

Rich Simpson, the OZ.org maintainer, replied to my email to say that the OZ.org wiki should be up and running next week. This is great news and I reckon we apply for usernames & passwords there and start transfering data once it's active.


Si

[jamesm]

Rich Simpson, the OZ.org maintainer, replied to my email to say that the OZ.org wiki should be up and running next week. This is great news and I reckon we apply for usernames & passwords there and start transfering data once it's active.

Good news.

I was having a think about the entire thing this morning. How does this idea sound:

- Documentation is collaborated on and formulated in the Wiki.
- Once a piece of documentation reaches a suitable level of maturity and factual completeness it can be put forward for adoption as an approved piece.
- If the maintainers and comitters agree on it's completeness and quality it can be translated to LinuxDoc or DocBook format.
- The documentation can then be archived and hosted in a similar way to www.tldp.org and made accessible to users who want some assurance that the documentation they're reading is up-to-date and accurate.

Have a think about this, the actual procedure will probably end up being quite different from this.

I also thought that the format of tldp.org was quite good in the sense that they publish HOWTOs, Guides, man pages, FAQs and articles. Breaking the documentation down into these user focused categories should make writing and reading the information easier.

[Harlequin]

Hi,

Glad to see this taking off.  I'm breathing a sigh of relief tbh.

I know it's a little early to get into something so detailed, but it's perfectly obvious that the reason that people use OZ over other roms is the versatility.  I myself bought the zaurus so I could ssh into work from a secure box and troubleshoot without having to bring a laptop.  Still the dream...

With that in mind, I think it'd be useful for a poll on what people use their zaurus for (or intend to use their zaurus for) and set up HOWTOs / guides on getting from 0 to functioning in x easy steps.

I'd guess that some of the major ones would be:
1. Functioning pda with pim
2. Portable wireless internet box (+ wardrive functionality, in some cases)
3. Sysadmin/operation tool
4. others...

Of course everyone would ultimately want a combination of such functionality, and there would be a common setup for most of the options.  There would be branches for whether you'd need extra / different functionality and so on...

The main aim, though, would be to document up to a run level that is of use to the user e.g. I don't use the pim functionality at all.  Current setups always leave me with a glowing box that is of no use to me, and I go back to my list of saved favorites and local txt files (product of hours in this forum) to get to where I want to be  I'm sure other people feel the same.

Harry

[jamesm]

With that in mind, I think it'd be useful for a poll on what people use their zaurus for (or intend to use their zaurus for) and set up HOWTOs / guides on getting from 0 to functioning in x easy steps.

I think we need to give people the information in a clear and ordered fashion and then let them use that information as they see fit.

However some of these options that you've suggested could well form the basis of a HOWTO or two, e.g. "How to setup your Z for use as a sysadmin tool".

The best way forward from that sense is to list these things on the Wiki, once its up and running and then see who can fill in the blanks.

The only problem I forsee with an approach like this is the duplication of a lot of information. This type of application specific HOWTO would probably be able to take over where a more basic HOWTO leaves off.

I.e. "This HOWTO is aimed at people who want to use their Z for xyz. But before you read this, you should make sure you've read the basic HOWTOs, which tell you what should be done to get your Z up and running"

(kind of like documentation dependancy)