Writing documentation

I have the daunting task of writing the documentation for ReceiptWallet. While I have some as well as some knowledge base articles, the docs need an overhaul. I wrote the previous version of the docs for Apple Help by hand. This time, I was going to look for a tool to do it. I found 3 options. HelpLogic, Simple Help Editor, and Mac Help Writer. The UI on the first two makes me want to barf. They say that they’re cross platform programs. For most programs, “cross platform” means “we have a crappy Mac UI in order to get it to work on Windows”. This isn’t true for all applications, but for many.

I tried to overlook the UI of these apps and the cost wasn’t an issue, but I couldn’t figure out how to use either program and HelpLogic kept saying that it couldn’t save my preferences and to check permissions. Not a good start. So I gave Mac Help Writer a try. It looked like it would work even if it did require me to use the format the author of the app wanted. I could live with that. However, there were 2 major flaws with the program. First is I couldn’t create ordered lists and second I couldn’t insert graphics. I went ahead and bought it and figured that I’d edit the files by hand after creating them.

Right before I went to bed and after I cranked out a bunch of help, I figured it out! I would use tokens and then search and replace later. So I’d encode < as %% and > as %%%; I’d search for the latter first and everything would work out.

To make things even easier, I created a shell script (with the help of Jerry Brady of Blue Circle Technologies) that automates the process after I use Mac Help Writer to generate the help.

#!/bin/bash
path_to_script=$(cd ${0%/*} && echo $PWD/${0##*/})
path_to_script_parent=`dirname "$path_to_script"`

cd $path_to_script_parent
cp -f Images/* ReceiptWallet\ Help/images/
cp -f Styles/* ReceiptWallet\ Help/styles/
cd ReceiptWallet\ Help/

WEBROOT="pages"
FILES=`find $WEBROOT -type f | grep html$`


for F in $FILES
do
    echo "    processing: $F"
    /usr/bin/perl -i -p -e "s/%%%/>/g" $F
    /usr/bin/perl -i -p -e "s/%%//
/g" $F
done

cd ../..
rm -rf Resources/English.lproj/ReceiptWallet\ Help
mv Help/ReceiptWallet\ Help Resources/English.lproj/

This makes my markup look kind of funny, but it seems to work and I’m now more than half way through my help!

Leave a Reply Cancel reply