OESF Portables Forum
Everything Else => Zaurus Distro Support and Discussion => Distros, Development, and Model Specific Forums => Archived Forums => Angstrom & OpenZaurus => Topic started by: Windrose on October 26, 2004, 10:57:00 am
-
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 (https://www.oesf.org/forums/index.php?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 (https://www.oesf.org/forums/index.php?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 (https://www.oesf.org/forums/index.php?showtopic=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
-
Have you seen the opie documentation at http://opie.handhelds.org/cgi-bin/moin.cgi/Documentation (http://opie.handhelds.org/cgi-bin/moin.cgi/Documentation) and in particular
Click and hold (http://opie.handhelds.org/cgi-bin/moin.cgi/OpieUserManual_2fUsingOpie)
-
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
-
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 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
-
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.
-
Have you seen the opie documentation at http://opie.handhelds.org/cgi-bin/moin.cgi/Documentation (http://opie.handhelds.org/cgi-bin/moin.cgi/Documentation) and in particular
Click and hold (http://opie.handhelds.org/cgi-bin/moin.cgi/OpieUserManual_2fUsingOpie)
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
-
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
-
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.
-
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
-
All,
Again, let's capture this for newbees. Can we open up a leg of the WIKI for a HOWTO.
Dan
-
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.
-
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
-
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".
-
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
-
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
-
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?
-
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 (https://www.oesf.org/forums/index.php?showtopic=6926). 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.
-
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
-
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.
-
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 (https://www.oesf.org/forums/index.php?showtopic=6926)
-
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
-
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
-
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/ (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... ?)
-
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.
-
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.
-
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
-
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.
-
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
-
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)
-
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.
-
Good point.
-
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
-
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) (https://www.oesf.org/forums/index.php?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
-
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!
-
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.
-
@ 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.
-
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.
-
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
-
Well, it seems that no temporary working space will be necessary after all: documentation can now be contributed to openzaurus.org (http://www.openzaurus.org/web/) 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.
-
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
-
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.
-
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!
-
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
-
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.
-
Btw I wrote Rich about my interim wiki when asking for a confirmation e-mail. No response so far.
-
2. sounds fine to me, just as long as we have a thread so that people can suggest things.
Si
-
It has occurred to me that my domain/web space is in fact a separate service from my DSL connection - which means it does not fall under the 1000MB limit. Option 1 is thus perfectly viable although I will consult my ISP before posting any URLs publicly.
I do feel a bit silly for having missed this little detail, sorry for any confusion. Given the circumstances, I would slightly prefer option 1 over option 2 - we need as many contributors as possible.
z.
-
I also prefer zenyatta's original wiki. We know the format (zenyatta did a great job with the contents page), wiki is easy and collaborative for everyone, and it's already set up--no waiting for passwords, etc.
So if #1 works, it has my vote, too.
Kent!
-
Hear ye, hear ye!
Anyone who wants to contribute to the new OpenZaurus User Manual effort should head over to http://www.journey.sk/zwiki/index.php/HowToContribute (http://www.journey.sk/zwiki/index.php/HowToContribute) where you will find a few guidlines to get you started. The User Manual is an open, unrestricted Wiki with a Table of Contents already in place and some sections already partially written. You are welcome to submit content, fix mistakes and add editorial comments at the bottom of each section. General editorial comments and discussions should be reserved for ZUG forums (either this thread or a new one). The aim is to eventually have a comprehensive manual that can then be ported to openzaurus.org.
z.
-
This is a good idea in my opinion as well. I would think that a natural layout (for a contents page, etc.) could be:
[...]
I have also put some thought into how to organize and structure the OZ page. I posted my ideas to the OZ mailing lists at the end of last month. I came up with something similar to ksignorini's ideas. You might want to take a look at
http://article.gmane.org/gmane.comp.handhe...aurus.user/9858 (http://article.gmane.org/gmane.comp.handhelds.openzaurus.user/9858)
http://article.gmane.org/gmane.comp.handhe...aurus.user/9895 (http://article.gmane.org/gmane.comp.handhelds.openzaurus.user/9895)
I really think the OZ site has to make sure it caters to the different needs of its different visitor groups (I sketched out three groups: people interested in OZ, plain users, developers).
-
Nice thought, although I think splitting "Docs" into "User Manual" and "Developer Manual" would make the visitor groups more distinct and expanding the menu by 1 item would be perfectly justified. "Docs" just feels very general to me. It can mean almost anything.