The Documentation Apocalypse

[Windrose]

I will try to keep this from partaking of the Rant nature, but I don't expect that to be easy. As I see it, there are sundry problems and not a few great improvements in using OZ 3.5.1, but for my money the true OZ "showstopper", to borrow otzenpunk's convenient word (https://www.oesf.org/forums/inde...?showtopic=7930) is the deplorable state of documentation for OZ.

What we are talking about here is a complex, subtle, very powerful computer operating system and a divers collection of applications that are ditto. And there is virtually no organized information on how to install, configure, correct or use any of it. Nada.

Yes, yes, yes, I know, there are some wiki pages on how to flash your Zaurus to the distribution of your choice. Molti ringraziamenti. It's like blindfolding you, leading you into the middle of the North Woods, and then giving you instructions for removing the blindfold.

Let me give you an specific example. I have this little problem in getting the Sharp CF camera module to work on my beloved SL 5600. (https://www.oesf.org/forums/inde...?showtopic=7849) RichS offered some advice beginning with

The first thing to try is to hold down the stylus on the camera icon to get the menu. Then make sure it runs with root priviledges.

Now, that, actually, is the first time anywhere that I've seen a reference to the Incredibly Useful Fact that holding down the stylus on an icon brings up any sort of menu. As it turns out, you can't affect much by holding down on the desktop icon, you have to bring up a file manager, nose around until you find the actual executable file, and then do the hold-down thing. But the point is I shouldn't have learned that from some chance helpful comment. Maybe it's buried in the Sharp documentation, but that's only the vaguest improvement over OZ. The camera, by the way, still doesn't work.

I have commercial apps I'm fond of, such as NeoCal and Stage One that almost-but-not-quite run under OZ 3.5.1. No clue why not. No docs. I've managed to get some ipkg functionality working, that involved serendipitous notes in this forum. I've seen references to some other package management system, but now I can't find them and it hardly matters because at the time it was imporssible to find any information on how it worked. Madness.

This basic issue comes up again and again. Cf. https://www.oesf.org/forums/inde...topic=7825&st=0. I have the sense that are  dozens of useful bits and pieces of information that have been discovered by the pitiable OZ user community, with some assist from the coders, but they are scattered to Hell and Gone through a dozen different wikis, fact sheets, fora (fori? forii? never could get that declension right), email lists and what-have-you. It's ridiculous. And it ultimately will kill the OZ effort.

Now I get it that the poor beleaguered OZ implementers, hardworking techies all, feel they do not have time to both produce dynamite free software and document it. I mean, they have to earn a living at some point. And have a life. But they might as well give up the software coding as well and do something much more fun and interesting, because without an adequate body of documentation, no one save half a dozen like souls will use their work. And then what's the point?

Myself, I'm a professional science and technology writer, and part of my ire stems from the sheer professional affront. Software documentation has been a snake pit since the first Altair or before, of course, but the OZ effort plumbs new depths. Hell, you need decompression stages to climb back out. I'd write it myself, heroically forgoing my usual exorbitant fees, but I don't know enough, as witness the Camera Debacle. Or the NeoCal Boondoggle. Or ... well, you get the idea. I'd be happy to work with the OZ team to develop Real Documentation if they'd like to send me some detailed information on how to make things work from the ground up, but I'm guessing that if they had that they'd have published something.

It's a shame, really. For all its flaws, the Opie distribution is a beautiful little piece of open source work. But I think it's doomed.

Windrose

[TimW]

Have you seen the opie documentation at http://opie.handhelds.org/cgi-bin/moin.cgi/Documentation and in particular

Click and hold

[lardman]

pitiable OZ user community

I don't want pity thank you. I'm quite happy as I am. ;-)

I have the sense that are dozens of useful bits and pieces of information that have been discovered by the pitiable OZ user community, with some assist from the coders, but they are scattered to Hell and Gone through a dozen different wikis, fact sheets, fora (fori? forii? never could get that declension right), email lists and what-have-you. It's ridiculous. And it ultimately will kill the OZ effort.

Righty-ho, let's sort it then.

but I don't know enough, as witness the Camera Debacle. Or the NeoCal Boondoggle. Or ... well, you get the idea. I'd be happy to work with the OZ team to develop Real Documentation if they'd like to send me some detailed information on how to make things work from the ground up, but I'm guessing that if they had that they'd have published something.

I think I know a few things; I am more than happy to help you.

The only issue at the moment is where to place the info. I would have suggested the OE wiki but this is to be for OE only. The OZ website it being revamped to include a wiki (but not public access). I guess I could get write permissions for it, eventually.

My main issue is that I don't know what people need to know (as I've been at this for a while now - difficult, once you know enough to write docs it's difficult to remember what people needed to know).

It might be worth while looking on the oe mailing list and talking to the chap who is re-doing the web site as this would be the best place to place the docs. I'm happy to help with the technical side (and I can even write farily coherently; at times ;-)). Either way I think we ought to produce an updated OZ FAQ and operating manual (in the form of the basic thing which came with the Z when you bought it).


Simon

[XorA]

Now I get it that the poor beleaguered OZ implementers, hardworking techies all, feel they do not have time to both produce dynamite free software and document it. I mean, they have to earn a living at some point. And have a life. But they might as well give up the software coding as well and do something much more fun and interesting, because without an adequate body of documentation, no one save half a dozen like souls will use their work. And then what's the point?

I think you totally miss the point. When I do something for OZ/OE I do it because I want/need it. I then send it to the mailing list in case someone else wants it. I dont do docs because I dont want/need them. I don't particularly care if no-one else ever uses my work I am happy in the fact it is working for me.

[dansawyer]

I agree this problem is significant.

A WIKI seems to be a reasonable way to address this. For a beginner to intermediate user OZ is difficult to comprehend. If a wiki is opened up I would offer to add content and editing.

Regards,
Dan

[nathanwms]

This is the perfect area for many OZ users who are not coders, but are using OZ on a daily basis to help out.  Quality documentation will increase the number of people who try OZ and many will probably stay with it, once they can get it configured for their needs.

Windrose, you raise a good point that is probably true to all distros.  The key is for more of us who benefit from them to give a little back in what ever way we can (coding, testing, documenting, money, etc.).

Hope no one is offended at a Cacko user commenting on an OZ issue.

[Windrose]

Have you seen the opie documentation at http://opie.handhelds.org/cgi-bin/moin.cgi/Documentation and in particular

Click and hold

No, I haven't. Thanks. An excellent example. I'm going to gloss over the entries with "documentation to come" and the typos and such, as no one is prefect and clearly they're trying to make the effort.

Now take me, the naive user looking for a new Zaurus OS build. I just googled the ZaurusUserGroup web site and the OpenZaurus web site and the OpenEmbedded web site for occurances of the string "opie.handhelds.org". It will come as no surprise to you, the experienced user, that I found no explicit, well-marked links to the Opie site and the work-in-progress manual. There were references here and there to email addresses at that site, or links buried in out-dated threads on some specific subject that I probably wouldn't have looked at. And some references in developers sections. A fairish number get non-existent page errors.

In the hallowed spirit of Monty Python ("Well I hardly think this is good enough. I think it would be more appropriate if the box bore a large red label warning lark's vomit."), I hardly think this is good enough. If your main GUI is Opie for goodness sake wouldn't it be well to point out early and often that the user can look there for help? Sometimes?

Windrose

[Windrose]

I think you totally miss the point. When I do something for OZ/OE I do it because I want/need it. I then send it to the mailing list in case someone else wants it. I dont do docs because I dont want/need them. I don't particularly care if no-one else ever uses my work I am happy in the fact it is working for me.

Actually, I think you miss my point, but since you're obviously happy, and apparently not a Useful Resource for the average user, I don't see that you need to get it. Thanks, anyway.

Windrose

[cycojesus]

Now I get it that the poor beleaguered OZ implementers, hardworking techies all, feel they do not have time to both produce dynamite free software and document it. I mean, they have to earn a living at some point. And have a life. But they might as well give up the software coding as well and do something much more fun and interesting, because without an adequate body of documentation, no one save half a dozen like souls will use their work. And then what's the point?

I think you totally miss the point. When I do something for OZ/OE I do it because I want/need it. I then send it to the mailing list in case someone else wants it. I dont do docs because I dont want/need them. I don't particularly care if no-one else ever uses my work I am happy in the fact it is working for me.

I don't know who missed the point here...
A strong point of free softwares is reusability so if whatever you do is so undocumented that nobody understand it and someone has to start writing the same thing you did from scratch then your contribution is completly useless, I would even say negative as you make people loose time trying to understand your work. Just imagine where free softwares would be if everybody acted like you... I'll tell you : it would be in the trash of history.

[Windrose]

I think I know a few things; I am more than happy to help you.

The only issue at the moment is where to place the info. I would have suggested the OE wiki but this is to be for OE only. The OZ website it being revamped to include a wiki (but not public access). I guess I could get write permissions for it, eventually.

My main issue is that I don't know what people need to know (as I've been at this for a while now - difficult, once you know enough to write docs it's difficult to remember what people needed to know).

I am at your service. Yes, doing the outline probably would be tedious. Perhaps the thing to do is solicit suggestions. Perhaps a new thread?? Some catchy title? Like OZ Manual Say Wha?.

Windrose

[dansawyer]

All,

Again, let's capture this for newbees. Can we open up a leg of the WIKI for a HOWTO.

Dan

[zenyatta]

Windrose: what a pleasant surprise to find a professional writer in our midst!

A couple of practicalities:

1. wikis tend to suffer from very uneven writing. If we are talking a serious user manual effort this has to be dealt with. We need someone who will either write the thing largely by him/herself, or do the necessary editing (not sure which of those tasks is more terrifying). Any thoughts? Volunteers?

2. For a long time, I used to write forum posts (with whatever advice I happened to have) with the broadest possible context. Alas, repetition eventually just got too tedious and now my posts tend to have that "ol' skool vibe". I get a feeling that there is a body of "fundamental knowledge", building blocks that all problem-solving discussions keep referring to. I think we should formulate this knowledge as the first step, preferrably in the form of a glossary so that terminology also gets established.

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

z.

[lardman]

For a long time, I used to write forum posts (with whatever advice I happened to have) with the broadest possible context. Alas, repetition eventually just got too tedious and now my posts tend to have that "ol' skool vibe".

:-D I know that feeling.

wikis tend to suffer from very uneven writing. If we are talking a serious user manual effort this has to be dealt with. We need someone who will either write the thing largely by him/herself, or do the necessary editing (not sure which of those tasks is more terrifying). Any thoughts? Volunteers?

True, but at least they can be used as a first step - then, if need be, the steps can be refined by a single editor (assuming people claim credit for knowing how to do such-and-such a thing so that they can be contacted to ensure that any editorial changes are in fact correct).

Perhaps have a wiki in which we have a number of sections:-

* Requests, suggestions for topics, etc. (the stuff that I'll have troubles thinking of)
* Draft explanations, etc. (so I can whack my explanation in there)
* Finished ('edited') explanations, etc. (where anything I've written which is too complex can be broken down into newbie digestible chunks for final distribution, etc.)

If we could nab a bit of the wiki here that would be great (in terms of both exposure and ease of use for me/us ;-); I assume it will eventually be moved (or at least replicated) on OZ.org.


Si

[zenyatta]

That was my third, unasked question: where should the documentation's hub be? OZ.org is the logical choice but ZUG is the pragmatic one. Maybe we should "incubate" the stuff here until it is stable, then do a one-time transfer to OZ.org. Of course, we need to define "stable".

[lardman]

OZ.org is currently being resurrected so it'll probably take a bit of time before it can be used usefully. I reckon do the incubation here (as we all have access) then move it across once it's more complete.

This way we can get started straight away (which I think is a good idea, especially as we all seem keen at the moment)


Si