[Koha-devel] Documentation review

[Mark Tompsett]

Greetings,

I personally do not like putting the command line prompt '$ foobar' into the 
code boxes. It makes cutting and pasting more time consuming. I think we can 
accommodate that level of laziness. :)

Additionally, like we discussed on the IRC channel, I think some people will 
out of ignorance add all three to a koha.list file if you put them all in 
code boxes. People who read instructions will see the oldstable and unstable 
entries. People who do not, will likely end up with unstable in their 
koha.list file because they did all three.

Also, the 'sudo ls' in the Ubuntu instructions is intentional, because 
otherwise running the wget straight up will expect a password, but it won't 
be obvious to the user. I'd recommend it.

Your instructions for Debian do not mention the configuration file checked 
for the creation of instances, nor do you mention koha-create-db parameters. 
Your instructions are English specific. The Ubuntu instructions mention 
where to change the ZEBRA_LANGUAGE (specifically for Spanish as an 
example). -- Thanks Pabloab.

Rather than summarize separate remote database, perhaps you should link to 
(and clean up as necessary): 
http://wiki.koha-community.org/wiki/Install_Koha_3.6_on_Debian_squeeze_using_a_separate_MySQL_server
*makes mental note for potential tweak to Ubuntu instructions*

The 'Access the web interface' section looks like if I do just those steps 
then Koha should be working. Someone is going to misunderstand, particularly 
if they are unfamiliar with Linux. This is why the Ubuntu packages 
documentation is so long. It's aimed at a lower technical level than the 
Debian instructions. If people can't install Koha, they will form a negative 
opinion of the software. Our instructions need to be written for the 
want-it-easily-installed-now, unfamiliar-with-linux user with respect to the 
packages. Instructions for a development environment should require a higher 
level of understanding, but I still don't believe we should force a level of 
geekdom on people who wish to try to dip their toes in the water.

Lastly, except for having to install sudo in the first place, which is not 
documented because sudo is installed by default in Ubuntu but not Debian (in 
my experience), the Ubuntu instructions work for Debian as well.

GPML,
Mark Tompsett