Additional editing guidelines for distribution manuals (Was: SHR first experiences & user manual)

Marko Knöbl openmoko.marko at gmail.com
Thu Aug 27 21:51:04 CEST 2009


2009/8/27, Risto H. Kurppa <risto at kurppa.fi>:
> Hi!
>
> Sorry for an ugly post.
>
> Now that I also decided to go for SHR I was requested [1] to check if
> the SHR user manual is factually correct.
>
> So here are some comments:
>
> "SHR (Stable Hybrid Release) is here to provide you with Root
> FileSystem images that you can easily install onto your Freerunner to
> use as a daily phone. It's filled with prepackaged software that can
> be installed upon demand by users"
>
> So I can off-line install the packaged apps? No, I bet you mean that
> is has stuff pre-installed and you can get more from the
> repositories..
>
> Reading http://wiki.openmoko.org/wiki/SHR_User_Manual#SHR_Specific and
> I already have the feeling that this hass too many tech stuff.. 'root
> filesystem image', 'ophonekitd' - is that stuff really required here
> to be able to use it? I prefer a nice smooth experience, easy for
> beginners too. Do I now need to go and find out what's ophonekitd?
>
>
> http://wiki.openmoko.org/wiki/SHR_User_Manual#Stability
> Maybe the difference of testing and unstable should be written here,
> not in the introduction?
>
> btw. a screenshot (or logo when there is one) would be nice to see on
> top of the manual page, it just would make it again a bit more
> appealing.
>
>
> http://wiki.openmoko.org/wiki/SHR_User_Manual#Installation
>
> Maybe the differencies of lite and normal image should be explained
> _before_ you tell where to get them? And somewhere later tell how to
> upgrade -lite to normal
>
> AFAIK only -lite images are currently available? (ok, dos1 explained
> newest fat images were broken and he removed it)
>
> Maybe 'source code' should not be in the 'installation' chapter but
> more of 'devel' or something like that.
>
> Image content: it'd be nice if there were links from the items to home
> pages. What's illume? What's vala-terminal? What's pythm?
>
> Installation: it might not be a bad idea to remind people to upgrade
> the phone firmware and QI/uboot (and maybe tell which one is more
> popular - see http://www.doodle.com/svvsubwnyn4zaxd3 )
>
> Anyway, these are the files I flashed:
> -rw-r--r--  1 rhk rhk 69992448 2009-08-08 17:49 lite-om-gta02.jffs2
> -rw-r--r--  1 rhk rhk    28596 2009-08-26 19:05
> qi-s3c2442-1.0.2+gitr243+36bb5c03756268ff15b2d95a043ffb39a919ce5c.udfu
> -rw-r--r--  1 rhk rhk  1832764 2009-08-16 23:32
> uImage-2.6.29-oe11+gitr119838+2d158aae9d8d36f575504f59884ed8e80802efe2-r3.5-om-gta02.bin
>
> flashing.
>
> I'd like to be able to have a dir on my uSD and mount it automatically
> as /home (on om2009 that was the folder bind-home on uSD) but I guess
> manually editing fstab will have to do. Maybe that should be explained
> somewhere here?
>
> How come the check of version is explained before the booting process?
>
> booting.
>
> Initial setup:
> Some lines about the possibilities there would be nice.. How on earth
> do I know what profile to select? Or what 'quick launch' is? Or why do
> I have to see screens where I only can select one item? ('irc' told me
> that the quick launch menu has no effect.. nice...)
>
> rebooting.
>
> Screenshot showing the wrench would be nice.
>
> The manual explains directly the wrench options - maybe SHR settings
> would be more important for usual settings instead of double click
> stuff etc..
>
> Maybe explaining SHR post-installation SCP commands could be done on
> SHR post-installation page instead of the manual. I think it's enough
> to explain what is it and why to run it and then link to the page.
>
> It isn't also told anywhere to run opkg update;opkg upgrade.
>
> Post-installation script would run opkg update, not upgrade. And
> here's a discussion telling the benefits of the script:
>
> 13:41 < rhkfin> Should I run the SHR post-installation script at
> http://wiki.openmoko.org/wiki/SHR_post-installation
> 13:42 < rhkfin> (as recommended in the SHR manual)
> 13:42 < DocScrutinizer> never heard of
> 13:43 < dos1> neither me
> 13:43 < DocScrutinizer> even "SHR-manual" !? wow o.O
> 13:43 < rhkfin> http://wiki.openmoko.org/wiki/SHR_User_Manual
> 13:44 < dos1> cellhunter?
> 13:44 < dos1> ...
> 13:44 < dos1> use openBmap ;P
> 13:44 < rhkfin> no, not cellhunter :)
> 13:44 < rhkfin> yes I will :)
> 13:44 < rhkfin> (being in ~top5 there :)
> 13:44 < dos1> Navit is already newest in SHR repo
> 13:44 < dos1> ffalarms is in image
> 13:44 < rhkfin> obexpush?
> 13:45 < dos1> dates/tasks - will be replaced by opimd apps soon and in
> shr image by default
> 13:45 < dos1> obexpush - hmm... i'll look at it and maybe include in image
> 13:45 < rhkfin> and I won't need them anyway..
> 13:45 < rhkfin> dos1: ok, great
> 13:45 < dos1> mokomaze.... why isn't it in fat image by default? o_O
> 13:45 < dos1> cellhunter - no comment :P
> 13:46 < rhkfin> dos1: is there a fat image around? I only find lite..
> 13:46 < dos1> rhkfin: newest fat image was broken
> 13:46 < dos1> rhkfin: so i removed it
> 13:46 < rhkfin> dos1: ah, ok
> 13:46 < dos1> rhkfin: on next regeneration it should be there back
> 13:46 ::: kvaster [n=kvaster at 93.84.112.80] has joined #openmoko-cdevel
> 13:47 < dos1> that script is useless
> 13:47 < rhkfin> I agree..
> 13:47 < dos1> SHR is open distro, so instead of doing such scripts
> they should improve default image ;x
>
>
> The manual should tell the USB-ssh-thing BEFORE suggesting the
> postinstallationfail -script.
>
> Replaced gsmhandset with
> http://www.kurppa.fi/freerunner/config_files/gsmhandset.state
>
> How about preferring nano over vi? I think nano - telling people what
> to press, might be more friendlier. People who know stuff will use vi
> anyway..
>
> Edited /etc/phone-utils.conf (btw it all was on one single line..
> Don't know if that's good or not..)
>
> opkg was called opkg-cl - I think I saw somewhere that this is a known bug.
>
> apps:
> ffalarms - installed by default (-> manual outdated)
>
>
> Swap - I'll skip that, I'll install another uSD soon with debian..
>
> Init opkg database - the > packages.txt - thing sound's stupid to me.
> Maybe explain here some general package management stuff.. like opkg
> upgrade.
>
>
> SHR is shipped without root password (just press enter)  - this should
> be told already somewhere near the usb-ssh -part.
>
> Locate lost phone by GPS and openbmap - maybe stuff like this
> shouldn't be explained in the manual? Maybe just link to a site with
> apps listed (sound's like the future application showroom :)
>
> opkg update;opkg upgrade took looong, maybe an hour or so.
>
> Localization - this is more interesting and important againt!
> How about some locale meta packaget to install tangogps-locale- packages
> etc..
>
> opkg install glibc-locale-fi
>
> opkg list|grep locale-fi returns tens of packages -any changes to get
> all required/available finnish packages installed? If I install an
> app, do I need to find the locale-package myself..?
>
> opkg install libframeworkd-phonegui-efl-locale-fi shr-settings-locale-fi
>
> shr-settings-locale-fi couldn't be found :/
>
> Adding
> export LANG=fi_FI.UTF-8
> export LC_ALL=fi_FI
> to /etc/profile
>
> root at om-gta02 /usr/share/shr/scenarii $ opkg list | grep illume-dic
> e-wm-illume-dict-pl -
> 1.0-gitr185+cff6bbd4b6773629e4172654a01bef63862f037d-r0 - Polish
> dictionary for Illume keyboard
> e-wm-illume-dict-pl-dbg -
> 1.0-gitr185+cff6bbd4b6773629e4172654a01bef63862f037d-r0 - Polish
> dictionary for Illume keyboard
> e-wm-illume-dict-pl-dev -
> 1.0-gitr185+cff6bbd4b6773629e4172654a01bef63862f037d-r0 - Polish
> dictionary for Illume keyboard
> root at om-gta02 /usr/share/shr/scenarii $
>
>
> Maybe some other languages should be added :)
>
> ran echo "" > /usr/lib/enlightenment/modules/illume/dicts/None.dic
>
> SHR settings - please explain this before any navigation/gps map stuff...
>
> I see that opkg doesn't have tab-expansion. Badly needed, a pain to
> opkg list |grep every time!
>
>
>
> Between data sync and car navigation you explain 'reporting bugs'? The
> best place for it? No..
>
> Navit installation can be done from default repo, no need to add
> custom repo or do the libgps trick.
>
> Don't explain navit maps here, it really isn't core SHR. Link to navit
> documentation (and fix it there if it isn't good enough). Don't
> duplicate..
>
> UI didn't go through the SHR settings part, I'll figure it out myself.
>
> opkg install navit tangogps pidgin openbmap-logger numptyphysics
> mokomaze openmoocow omgps gpe-scap coreutils-locale-fi nano-locale-fi
> pidgin-locale-fi
>
> Installing software is explained in the very end of the howto. Not good.
>
> Replace dropbear with openssh - why should I want to do this?
>
> System customizing, didn't really read it.
>
> I suggest you split the documentation to more than one site:
> 'installation' 'applications' 'settings' 'connectivity' or something
> like that, and create a wiki category and table of contents or
> something, just to make it easier to read.
>
> opkg install navit-locale-fi tangogps-locale-fi
> There. Anyway I think I now have a working SHR installed and I hope
> thesee comments will help improving both SHR and the howto.
>
> Thanks people for your work! It's great that you've done work on the
> manual, it has lots of good stuff in there!
>
> (next I'll try Paroli on SHR.. :)
>
> And sorry for a messy post..
>
>
> r
>
> [1]
> http://risto.kurppa.fi/blog/great-news-from-the-openmoko-community/#comments
>
> --
> | risto h. kurppa
> | risto at kurppa dot fi
> | http://risto.kurppa.fi
>
> _______________________________________________
> Openmoko community mailing list
> community at lists.openmoko.org
> http://lists.openmoko.org/mailman/listinfo/community
>
After reading this excellent statement from Risto I realized that we
should expand the guidelines for writing manuals on the Wiki [1]

The issues I want to address with these additional rules are:
1) If there is a problem with a distribution several editors are
adjusting the instructions on the manuals instead of reporting bugs.
2) The SHR manual is getting very long because there is much
information on additional applications (Risto mentions Navit and
sms-sentry)

I'd propose adding these additional rules to the Wiki Editing Guidelines:

1) As the distributions are still under development the manuals may be
helpful by presenting important known issues and how to fix them. If
you want to add a notification about an issue to the manual, always
add an invisible comment with an URL to a bug report for the problem.
For example (this is an obsolete problem which occured in SHR):
"Please note that the standard SHR alarm application does not work if
the phone is suspended. You can fix this problem by installing
ffalarms <!---bug report: http://shr-project.org/trac/ticket/543--->"
If there is no bug report yet you will have to create one. Reported
problems which do not link to a bug report or link to a closed bug
report should/can be deleted.

2) In the distribution manuals there should only be instructions for
applications which are preinstalled on this distribution. If you want
to write a manual about an application which is not preinstalled on
the distribution you may create a seperate manual for that application
or use the application page.

Is it okay if I add these rules to the Editing Guidelines?

[1] http://wiki.openmoko.org/wiki/Openmoko_Wiki_Editing_Guidelines#Manuals



More information about the community mailing list