OESF Portables Forum

Everything Else => Zaurus Distro Support and Discussion => Distros, Development, and Model Specific Forums => Archived Forums => Angstrom & OpenZaurus => Topic started by: pframpton on February 14, 2005, 08:42:00 am

Title: Oz Documentation Project
Post by: pframpton on February 14, 2005, 08:42:00 am: There have been many rants and raves about the lack of documentation for OZ. I plan to put together a set of manuals for as many applications as possible. Not just a collection of tips/tricks/FAQs but a comprehensive manual on using the programs.

For this I will need volunteers. The first stage is to write quides for the most important/common applications. I welcome suggestions on which apps these are, aswell as volunteers to write documentation.

Ideall the document for an app will include:

Installation
Configuration
Use
Bugs/Trick/Tips
Links to source, more info, etc

I have started a webpage at OZ Documentation Project (http://users.ox.ac.uk/~scat1139/oz/index.html)

I can be contacted by e-mail (details on the link above). Let me know which apps you want to write about and I will update the details on the website.

Philip

PS Could the admin pin this post to the top of the forum please?
Title: Oz Documentation Project
Post by: lardman on February 14, 2005, 08:49:54 am: Let's get writing everyone.

Si
Title: Oz Documentation Project
Post by: Merardon on February 14, 2005, 12:03:13 pm: What would be particularly helpful would be a short description of all the packages installed by default, to aid in uninstalling the unessential ones. (Freeing up space) The information could then be integrated into the package manager via a description button. Unless this already exists, and I merely haven't located it yet.
Title: Oz Documentation Project
Post by: lardman on February 14, 2005, 12:29:52 pm: The packages file contains a short description of each package - ipkg info <packagename> spits this info out to the terminal.

This would be a useful addition to aqpkg/opie-package-manager (IMHO), and may already have been suggested added (you'd need to check the opie bugtracker).

Edit: This functionality does exist in opie-packagemanager

Si
Title: Oz Documentation Project
Post by: mimeca on February 14, 2005, 02:17:36 pm: Hi pframpton

I would like owrk in that project. Zaurus isn't for newbies and a good documentation can help. I can write some documents in english, but my language is spanish.
Title: Oz Documentation Project
Post by: Hrw on February 14, 2005, 06:14:06 pm: in opie-packagemanager try to hold on package - infos will open
Title: Oz Documentation Project
Post by: Merardon on February 15, 2005, 02:00:52 am: From the packages I tested that out on, it didn't really tell what the package was, and what it was for, merely what it was called, space, what it requried, etc. Perhaps adding a small description of each package there would be helpful?
Title: Oz Documentation Project
Post by: pframpton on February 15, 2005, 04:59:59 am: Quote
Perhaps adding a small description of each package there would be helpful?
[div align=\"right\"][a href=\"index.php?act=findpost&pid=67086\"][{POST_SNAPBACK}][/a][/div]

This puts the burden on the maintainers rather than the volunteer document writers. They (the maintainers) have enough to do. This is why the description fields are minimal.
Title: Oz Documentation Project
Post by: lardman on February 15, 2005, 11:08:05 am: You could submit a patch for the .bb file to alter the description if you don't think it's descriptive enough.

Si
Title: Oz Documentation Project
Post by: Merardon on February 24, 2005, 02:08:43 pm: I don't know enough about the packages to write up descriptions, unfortunately,and if I did, I wouldn't have requested the feature in the first place. I was implying a volunteer, actually.
Title: Oz Documentation Project
Post by: Merardon on March 22, 2005, 12:16:40 am: Are you alive, pframpton? You haven't responded to the e-mail that I sent weeks ago, my proposed fixes haven't been added, and it's not been moved to OESF.
Title: Oz Documentation Project
Post by: pframpton on March 23, 2005, 01:01:29 pm: Yes, I'm alive. What message? Do you mean texteditor documents, if so I only just found it in my junk box, I've whitelisted you now.
Title: Oz Documentation Project
Post by: Merardon on March 23, 2005, 09:36:32 pm: It was essentially just what I said last post, and was an e-mail from harpalus hush ai (insert the @ and ., respectively) I'll have enough time to write up something in a few weeks, so I can start contributing then.
Title: Oz Documentation Project
Post by: acpkendo on March 29, 2005, 10:45:44 am: Quote
Do you mean texteditor documents, if so I only just found it in my junk box, I've whitelisted you now.

opie-textedit docs were from me, opie-write or Hancom (probably not tinykate) to follow. . .
Title: Oz Documentation Project
Post by: pframpton on March 31, 2005, 05:00:57 pm: Before too much more is written, it would be good to produce some documents based on the OPIE and GPE documentation. No need to write instructions form scratch when the basics are already done.

I'm working on an the main manual PDF at the moment. Copying across info from the OZ website. Hopefully we can have a 0.1 release manual, based on what is done so far, ready for OZ 3.5.3.
Title: Oz Documentation Project
Post by: dranath on April 07, 2005, 06:10:35 pm: Hello guys,

I only recently registered in this forum and right now I'm still looking which ROM to dedicate my SL-6000L to :-).

So I would like to contribute my gained knowledge to the manual-efforts if I decide on to run OpenZaurus with OPIE or GPE.

But one question:
Browsing the Homepage of openembedded.org I saw their Wiki. Would it be possible to ask them to be able to put the manual there? So everybody registered and working with OpenZaurus would be able to contribute to the manual - and not have a single person to maintain it (and in case recode the html-pages sent to him/her).

Greetings
dranath
Title: Oz Documentation Project
Post by: BeKind on May 02, 2005, 11:58:50 pm: I agree with Dranath. Lets make the manual a Wiki.

I've spent so long getting OZ to work and learning the ins and outs of everything, that I think I should be contributing to a manual.

Because theres probably a few dozen people just like me, it should be a Wiki.
Title: Oz Documentation Project
Post by: lardman on May 03, 2005, 07:14:45 am: If you register on openzaurus.org you can create and edit wordpress docs there.

That is the preference as oe.org will eventually be just about the build system, not the ROMs which are built with it.

Si
Title: Oz Documentation Project
Post by: offroadgeek on May 03, 2005, 10:28:14 am: Why don't you all just carve out a section of the OESF wiki for OZ?
Title: Oz Documentation Project
Post by: zenyatta on May 05, 2005, 08:37:08 am: A while ago I set up an OpenZaurus wiki at my homepage - http://www.journey.sk/zwiki/index.php/UserManual (http://www.journey.sk/zwiki/index.php/UserManual). This was shortly before the big OESF changes etc. If anyone feels like it please feel free to work there. The site is being backed up once every 24 hours. As soon as I solve the most pressing problems with my newly-flashed 3.5.3 I will start contributing as well.

z.
Title: Oz Documentation Project
Post by: Mickeyl on May 05, 2005, 09:28:45 am: This is a good structure. Now could you all please settle one one wiki - preferably the "official" one @ openzaurus.org?
Title: Oz Documentation Project
Post by: acpkendo on May 05, 2005, 11:43:11 am: Having all of this on a wiki is a good thing, but I think the higher priority should be making sure that there is some documentation on the device itself. Many of the *-help-* packages in OZ right now do not have any significant documentation to them (some are just an index page with a header). This is certainly an area where we can help take the burden off the developers.

So, we might want to think about some way we can pull the documents off the wiki and format (also HTML) them for inclusion in the *-help-* packages. I don't know if something like DocBook would be good to standardize on down the road, since you could write once and publish to HTML (you could specify both regular format for the wiki and smaller format for the Zaurus, I assume) as well as a "comprehensive" PDF manual.
Title: Oz Documentation Project
Post by: zenyatta on May 06, 2005, 07:54:30 am: Mickeyl: The openzaurus.org site allows me to attach comments to an article but does not let me edit the article itself. So it is not really useable as a wiki.

If there is a proper wiki section I couldn't find it (I used the search textbox in the top-right corner). Maybe I need to register somewhere in order to edit articles but I could not find a registration screen either. If I need to register and then beg someone for edit privileges, I won't bother.

Cheers,
z.

EDIT: Silly me, I just found the registration option under Login. I'm waiting for my password to arrive.
Title: Oz Documentation Project
Post by: Hrw on May 06, 2005, 10:59:42 am: zenyatta: password send

use "Write->Page" to write documentation. We will talk about it later
Title: Oz Documentation Project
Post by: pframpton on May 10, 2005, 01:39:33 pm: I never got my registration password from OZ. I'll try again when I have a gap in thesis writing, and upload all the instructions people have sent me (not many).
Title: Oz Documentation Project
Post by: Hrw on May 10, 2005, 05:07:35 pm: @pframpton

I'm sending passwords usually once per day. If you registered after 2005-05-06 then I will send password tomorrow - had no time during last days - my grandmother died.
Title: Oz Documentation Project
Post by: zenyatta on May 10, 2005, 05:08:17 pm: Thanks for the password. As a first step, I have revised installation instructions for SL-5500 and SL-5600. The text was very comprehensive and informative but I thought it could use some improvements. I had two major goals in particular:

1. Making the text as friendly to an absolute newbie as is humanly possible.
2. Making important pieces of information more visually distinct.

In order to help with goal number 2, I introduced two CSS styles through a <style> tag:

.tip { font-style: italic; color: #004000 }
.note { font-style: italic; color: #802000 }

However, wordpress suppresses them which I think is a shame. If someone could add these two rules to the stylesheet used at openzaurus.org (perhaps with more sensible colors) it would help raise the quality of all wiki contents.

The revised installation instructions are at http://openzaurus.org/wordpress/not-in-men...l-5600-revised/ (http://openzaurus.org/wordpress/not-in-menu/install-on-sl-5500-sl-5600-revised/). I would appreciate feedback from anyone - please leave comments under the page. If the feedback is positive, we can replace the original instructions with this new version and I will proceed to revise more pages in a similar style.

Cheers,
z.
Title: Oz Documentation Project
Post by: lardman on May 10, 2005, 06:10:36 pm: zenyatta,

do you have a 5600? See my note on your page in wordpress. The flashing processes for the 5500/5000D and 5600 are different.

Seems nice and clear though.

Si
Title: Oz Documentation Project
Post by: zenyatta on May 11, 2005, 02:49:41 am: It's rather embarrassing to make a typo in the headline of a supposedly revised page I humbly thank you for pointing it out. The text is actually not intended for the 5600 at all. It is now fixed (same URL).

z.
Title: Oz Documentation Project
Post by: Hrw on May 11, 2005, 03:01:36 am: zenyatta: good work - thx.

css styles added
Title: Oz Documentation Project
Post by: lardman on May 11, 2005, 05:29:56 am: zenyatta,

no worries

Si
Title: Oz Documentation Project
Post by: obergix on November 12, 2005, 05:53:41 am: What has happened on that front ?

The pinned article points to a disappeared page...

Any plans these days for a stable wiki in which to contribute to documentation for the users (for the developpers it's there and pretty good actually

Best regards,
Title: Oz Documentation Project
Post by: lardman on November 12, 2005, 07:10:27 am: The openzaurus site is still there and the links should all work, I think that's the best place.

I've been a bit busy, hence my lack of having done anything very much,

Si
Title: Oz Documentation Project
Post by: obergix on November 13, 2005, 12:01:42 pm: Quote
The openzaurus site is still there and the links should all work, I think that's the best place.

I've been a bit busy, hence my lack of having done anything very much,

Si
[div align=\"right\"][{POST_SNAPBACK}][/a][/div] (http://index.php?act=findpost&pid=103445\")
Still this link is dead...
[a href=\"http://users.ox.ac.uk/~scat1139/oz/index.html]http://users.ox.ac.uk/~scat1139/oz/index.html[/url]

so maybe the pinned article may be updated to reflect current status ?

Thanks anyway
Title: Oz Documentation Project
Post by: lardman on November 13, 2005, 01:02:38 pm: Ah, I see, missed that one.
Title: Oz Documentation Project
Post by: lardman on March 31, 2006, 09:38:23 am: Right, all docs related stuff moved to here:

https://www.oesf.org/forums/index.php?showtopic=18472 (https://www.oesf.org/forums/index.php?showtopic=18472)

Get writing guys (and girls).

Cheers,

Si