My first real experience writing user docs

So today at 10:00am I embarked upon my first real attempt at writing user documentation. Spheriosity has been long overdue for some good user documentation. After all, the whole purpose of the application is to help people understand spherical geometry, so if they can’t use it then the program is worthless.

I decided that the best choice for writing the documentation was going to be LaTeX my favorite text processing language. I fell in love with LaTeX when I saw how it could format mathematical equations with ease. I use it almost 100% these days and it makes the most beautiful looking documents! It is suited perfectly for a code oriented person like myself as well because at times it feels like I am programing the document more than anything. Perhaps I will write more about LaTeX some other time.

Also because of LaTeX I realized that I might be able to run latex2html on the document and thus have something I could post on the internet. I have never been a complete fan of the output of latex2html mainly because I think it should have an option to let you view an entire section at once. I’m sure that for some things it is quite nice that it splits up into subsections and then subsubsections if you use them, but for this it doesn’t translate well.

I found that I don’t really mind writing user documentation as much as I thought I would. It’s kind of like commenting code to me. I know a lot of people don’t really enjoy commenting, but it never bothered me much. I feel like it is taking the necessary steps to ensure another human, or possibly myself, will be able to some day figure out what I was thinking. After spending lots of time writing a piece of code it seems worth it to put in that extra effort. I feel the same way about documentation. If it is able to help even a few users work with my application then I consider it well worth the effort. So far I have created 28 pages of documentation. Now, it is not solid text because there are pictures of the program as I try to visually walk the user through certain steps.

I spent a good 10 or 11 hours writing the documentation and I need to take a break from it for sure 🙂 Tomorrow will be a new day and I hope to finish the documentation and place the new alpha build on SourceForge. I don’t know if I could write user documentation all day every day, but it is good to know that I can do it when I need to. I admit that I felt a bit bad not writing any code all day (except a small perl script), but it was for a good cause.

I had a bunch of good ideas about things to write about today so hopefully I will have some material for the next few days. That’s it for today though… I need to get some sleep 🙂

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: