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

[Marko Knöbl]

2009/8/27, Marko Knöbl <openmoko.marko at gmail.com>:
> 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
>
Hi! I have just updated the Editing Guidelines. I diverted a little
from my original proposal. I hope that's okay. Further comments are
welcome!

marko