The Documentation Apocalypse

[Miami_Bob]

A comprehensive glossary - jargon list would be a very welcome & useful tool.

When I started following the topic, it was completely opaque as to what OZ, OE, Opie & so forth actually *were* and how they related one to another.

Such a list of terms & definitions would not only keep new users from having to guess from context the meaning of each word, such a list would also allow the experienced users to speak up when they disagree with a definition or find one to be incomplete, erroneous & so forth.

This (IMHO) is even more essential that the "basic" Wiki.

[lardman]

Good point.

[ksignorini]

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"

This is a good idea in my opinion as well.  I would think that a natural layout (for a contents page, etc.) could be:

1.  How to install OZ (including hows/whys to choose Opie or GPE, etc.)

2.  How to configure OZ after initial install.

3.  How to install software using package managers and ipkg.  (this would also include configuring feeds, how to put a feed on a cf, what a feed IS, etc., etc.)

4.  How to use your Z for ...

5.  How to use your Z as a ...

6.  Using your Z to do ...


This way there is a natural progression for beginners and without the "...before you do this do that..." which is not as intuitive as do this, then do this, then do that, then do that...

As well, step 3 should not have anything in it that you would normally have to do at step 2 to accomplish step 2.  That way, if I already have OZ installed (managed it on my own through someone else's instructions) and all I wanted to do was figure out how to configure it, I shouldn't have to read a section on installing software to know what I need to know.

I also think that we need to not only have this info online, but it must somehow also be included as an e-book or at least a readme text file inside the actual OZ distro image.  That way, a total beginner who has installed OZ at least has some chance of finding information on where to start.  It would have saved me countless hours, posts, etc.  It could be a single text document (at least with some basic info on step 2 setup and instructions on where to find steps 3 to ... online) that shows up in the Documents tab or in the Settings tab.  Sort of a single file "Start Here" doc.

Any other thoughts?

Kent!


edit: typo and addition and clarification

[Windrose]

I think something along those lines is the general consensus. On a related item of business, in the wake of my plaintive cry (captured in https://www.oesf.org/forums/inde...showtopic=8175), I've actually managed to install OZ 3.5.1 and Opie on my SL5600 (several times) and even installed and got to work sundry Useful Things such as the opie-reader, neocal, opie-eyes, and opie-camera in conjunction with the Sharp CE-AG06. Cognoscenti of these pages will recognize the last, in particular, as a serious piece of winnage.

So I'd like to take a moment to thank everyone who patiently helped with advice and pointers and bits of data. I think in particular of lardman (to whom I owe a beer or two), zenyatta, mos' likely dansawyer, Mickeyl (probably another couple of beers there) and sundry others, some of whom would inevitably be omitted if I tried to make a complete list. (One of the lesser-known corollaries of Goedel's Theorem.)

Thanks very much.

I'm trying to make notes of where I went wrong along the way on the theory that it might point up potential common errors. I'm pretty common.

StageOne! still refuses to run, currently complaining

Error while loading shared libraries: libsl.so.1: cannot open shared object file: No such file or directory.

Anyone happen to recognize that? It's a library in the /usr/QtPalmtop/lib directory in the Sharp distribution, but I don't recognize it as part of the standard OZ feed.

Windrose

[ksignorini]

Windrose:  

I have to completely agree with you on the support from these boards.  I also must thank lardman and zenyatta, for without their unending patience (both on the boards and in PM) I would not be using OZ today (just one week after receiving my SL-5500) and would have undoubtedly cratered and return to the stock Sharp ROM.

Thank you all so much.

That said, let's get this doc party underway!  As I said earlier, I'm sure I can find some time or submission data.  At the very least, I have very recent memories of what did and didn't work and where my mistakes were in setting up OZ on my Z (as it all happened in the last 7 days).

Kent!

[Mickeyl]

Bummer. Applications requiring Sharps libsl.so will probably never work on OZ, but try grabbing a libsl.so from a SharpROM and put it into $OPIEDIR.

[acpkendo]

@ Windrose

IIRC, libsl is a proprietary library made by sharp.  As such, OE couldn't legally re-distribute it.  However, having paid for your zaurus, I believe you have a right to use it whether as part of Sharp's ROM or any other.  You might be able to take it out of the Sharp ROM (unfortunately you'd have to re-flash the Sharp ROM, copy that to a card, and re-flash OZ) and use it with oz-compat.  I plan to do that myself in my eternal quest to get Hancom Office and the Sharp PIM apps working on OZ 3.5.1. . .

PS I also second ("third"?) props to lardman, mickeyl, zenyatta, and all the other OZ developers and gurus.

[zenyatta]

I believe the reason why OZ doesn't use libsl or other closed-source code is a strategic one rather than a legal one: if libsl is ever shown to be buggy/misbehaving there is no way to fix it independently of Sharp. And given Sharp's attitudes it's quite understandable OZ folks don't want to rely on it.

Personally, I think libsl has been field-tested so rigorously it's very unlikely a major bug should crop up - but I still like this self-reliant attitude and it's one of my reasons for sticking with OZ.

[bkarnes]

I would like to offer my services.  I am a Web Developer/Technical Writer (been going on 16 years).  Most of my work has been in the windows world, but I have transitioned over to Linux about 4 years ago (running Read Hat/Fedora Core 2).  I bought my SL-5600 about a year ago with the promise of something "wonderful", but have been sorely mistaken.

I have been following the Open Zaurus world for about 6 months waiting for it to hit for the 5600 and now it has!  I flashed everything and love it.  Now to get down to business.

I am in the military so I will be overseas for extended streatches of time (with enough down time for editing, writing, etc.).  I will still have e-mail/Internet access so I can still help.  Plus, I will be taking my laptop (dual boot XP/FC2 - I use FC2 mostly, but need the windows for the poor souls who don't know about Linux).

Let me know how to help.

Benny

[zenyatta]

Well, it seems that no temporary working space will be necessary after all: documentation can now be contributed to openzaurus.org after registering and e-mailing Rich Simpson (the admin). The registration procedure does not work quite smoothly (I did not receive my confirmation e-mail) but you can always e-mail Rich to get your account enabled. I plan to submit a few items tonight so let's go  

z.

[lardman]

I've registered and have just emailed Rich to ask for wiki write rights (try and say that one ;-).

What are you thinking? - copy the headings and what's in there already across to OZ.org?


Si

[zenyatta]

Well, I still haven't received any reply from Rich but I found out that I can log into the site. Having said that, I don't seem to have any permissions yet. No Edit icon anywhere, I must say I feel quite lost over there. And sometimes the site does feel slow. I suggest if you have text that's begging to be written just use the interim wiki and don't worry about it. I'm sure we'll get Rich cooperating eventually

And yes, I was generally hoping to reproduce the structure we had come up with but it isn't that simple - we will have to integrate with the OZ.org main menu which contains

About OpenZaurus
Getting Started
Docs

The way I see it, About OpenZaurus should contain some of what I had planned for Introduction (what OZ is), plus the Is OZ right for you? section. GettingStarted should contain quick install instructions (Zero to Opie in 5 easy steps) with pointers to sections of Docs. The Docs entry should perhaps be split into a User Manual and a Developer Manual.

Within User Manual, the "Is OZ right for you?" section would be scrapped and Introduction would instead contain stuff like minimum knowledge requirements, typographic conventions etc. (i.e. it should strictly become an introduction to the manual rather than OZ itself).

A sidepoint: I think we should limit ourselves strictly to the "latest widely deployed version" i.e. 3.5.1 at the moment, and version the manual along with OZ releases. What I mean is that we shouldn't clutter up the text with "but in 3.2 it works like this:".

z.

[ksignorini]

I'm with you re: 3.5.1 vs. older versions.  I think the about/getting started/docs structure is OK, but I quite liked what we were going to do with the wiki.  Perhaps we should invite Rich to look at our original (our=zenyatta's) concept wiki.

Kent!

[lardman]

zenyatta, as long as your site can take the traffic I'd be tempted to put the stuff in and edit it there, then point Rich to it and say words to the effect of "is this okay", and then move it over.

Your open wiki has the added advantage that it's very easy for OZ newbies to add items (thinking about this, perhaps there should be a page where people can request an explantation of something - or something along those lines?)


Si

[zenyatta]

The thing is, my DSL plan has a 1000MB/month cap (which means the sum of all my uploads + downloads must be 1000MB at most). The byte counter is off during weekends and holidays (so that I can download the occasional distro) and it's very very cheap. I never expected to host a public collaborative writing project.

Having said that, I also find the interim wiki to be very flexible. I thought about talking to my ISP about switching to a true flat rate plan (same price, lower speed) but I doubt it can be switched mid-month and I'm not really thrilled about slower net access either. The realistic options I see are

1) using my interim wiki (with me keeping an eye on the counter and pulling the plug if things get out of hand)
2) each of us asking offroadgeek for credentials to work within the ZUG wiki
3) asking offroadgeek to set up another, unrestricted wiki along with daily backup scripts (which I can provide, at least for phpWiki)

Option 1 would mean that we may suddenly end up without a wiki. Option 2 means that not everyone would be able to contribute (is that a drawback?) - still, everyone would be able to at least comment through a forum thread ("Documentation Resurrected", anyone  ). Option 3 sounds like lots of work for offroadgeek but let me tell you, this phpWiki thing is ridiculously simple to set up, at least with flatfile storage.

My personal preference is option 2.

z.