Everyone Loves Documentation...

And if you believe that, do I have a car to sell you! I recently had the wonderful pleasure of printing a binding a manual. The whole point of software is to save paper and then they need a manual printed out because they can't read it on the screen. They need to be able to hold something in their hands, and write on it and mark it all up with little notes to themselves.

All of our documentation is saved in HTML files. There is a lot of stuff in there that does not need to be printed (certain links and notes). All the images need to be resized to fit on 8x11'' paper. Page breaks need to be set up correctly. So on and so on.

The first issue was trying to get the HTML files to export out of our software with all the correct style sheet stuff. We had some export code but I seemed to need something more specific for the job so I ended up writing some new code. This handled stuff like getting rid of the screen style sheets and using the print style sheets for everything, ignoring pages that were tagged to hide, and evaluating calls to standard code. Good.

So then I had one huge HTML file that was formatted pretty much the way I wanted it to print. Now I wanted to add a table of contents. For the life of me I could not get the HTML file, exactly the way it was, into a text document to add a table of contents. The images would resize, I would lose the page breaks, and things that were supposed to be hidden would start showing up. So, fine, I would just have to add something to my new manual exporter to add a list of the contents at the beginning if wanted. So I whipped up some code to run recursively through the pages that were to be include in the document being exported and to add them all to an unordered list with gradually shrinking font size. That turned out pretty good. No page numbers but the order of how things appear in the document is there so you can find the section and the general area the documentation you are looking for is in. There, all I have to do now is print it.

Of course, three seconds after I finished printing it out it was already out of date. Not to mention that printing it out took a good couple hours. Of course I started it one night before leaving the office only to come in the next morning and of course find the printer out of paper. So then I had the pleasure of making enemies of anyone trying to use the printer the next morning and of sifting through hundreds of pages of help looking for someone's one page task report. So, after all that is done, I hear "That was supposed to be in color". DOH!! Well I'm not reprinting it all now. This will have to do and I will make sure to do the next one in color. Since I already printed the whole manual in black and white that I would make sure to do the covers for each module in color. So I print them out on some nice card stock and get the wholes all punched out for binding and I hear "You didn't laminate those?". Ugh!! Nope, I didn't laminate them. I'll remember that for next time. Honest! Then to binding. Heaven forbid the binding machine should take a break and just work with me long enough to get this done. I end up binding them all by hand (which is just fine because it was probably quicker then trying to figure out that stupid machine. Hmmm...I sound like a user!). You would think that having to write documentation is bad enough as it is, but then you have to print and bind it.

I don't know how to make the process any less painful. I guess the next time I have to do it all the code will already be written (great, the fun part will already be done). I used the export method I wrote to generate a PDF file for each module so that when the next customer wants a manual done I can just tell someone else where to get the PDF files and they can do all the printing and laminating and binding and then I won't have to worry about remembering to do it right. Which is good, because there are so many other things to worry about the documentation being in color.

The Aftermath of Friday the 13th

Well, I was right. It was definitely interesting. I was involved in a car accident and we ended up sinking in 10 feet of freezing cold ice water. Amazingly we escaped relatively unscathed. I was in shock for most of the weekend. It still feels like some crazy bad dream or something that only happens on TV or in the movies. This isn't supposed to happen to normal people. So now our car is gone and we are left cleaning up the mess left behind. Dealing with insurance and moving from borrowed vehicle to borrowed vehicle while we wait for our settlement. We also have the pleasure of having to tell our terrifying story over and over to everyone who asks what happened. And then we get to hear over and over again how lucky we are to be alive and how close we came to death and one small thing could have happened and we would have been toast. Now this only reinforces the terrible feeling we already have about what has happened. So I have basically been trying to tell everyone the story so that it's all over with and I won't have to do it any more. It's actually going pretty well. The first couple times I was pretty shaky but now it's not so bad. All I have to do now is figure out how to make the small things that used to be so important feel important again. It's funny how something like that can make everything look so different. All of a sudden I feel like I have no time left and so much to do. I haven't hardly even taken a break at work since for fear I will leave things unfinished. My favorite TV shows don't seem so vital to see. I hardly ever feel like eating any more. Sleeping is most difficult. I'm sure this is only a temporary state of shock and stress but it still makes life more difficult at a time when it sucks pretty hard already. I guess you just suck it up and hope you take away something good from the whole experience. And like everyone tells us, I guess we get to go car shopping now. Woohoo! Unfortunately I think that car shopping is one of those things that are fun if you choose them and painful if forced to.

Friday the 13th

Tomorrow is Friday the 13th and with the way things have been going, tomorrow should be interesting. But at least it's still a Friday.

When it snows...

It storms! Like things weren't bad enough already. We totally hooched our last round of updates. It was pretty bad. So now everyone is really tense and grouchy. I thought it was bad before. Everyone is disappointed and getting a little down about the whole thing I think. Not a whole lot has gone right this time around. It would be nice to see something go smoothly. It's getting to the point where it seems like no matter what we do, something is going to explode. And that always leads to grouchy, paranoid behaviour (sometimes good, sometimes bad).

Well, maybe tomorrow will be better. Eventually it has got to get better, right? I guess if it doesn't, we'll all be out of jobs soon! And then it won't really matter anymore.

Is it Friday yet?

We are at the beginning of a release and things are a little tense. Stupid bugs that never should have made it out to the customers are appearing much to often for anyones comfort. At least the updates are going smoothly. It's everything after that that is making everyone sooo irritable. And I don't know how to fix it. It happens every release. We try so hard (pair programming, writing tests, manual testing, etc.) to keep bugs from getting out but they always seem to and when you go to fix them it's always "Well didn't you test this?" or "Did anyone review this?" or "How could we be so silly?". And, of course, everyone is on edge already so everything sounds/feels like an attack and that just makes everything worse.

So why are we like this? There isn't really anything anyone can do about the errors that get out to the customers. Once they are out, the only thing we can do is fix them. But, it's like, everyone feels like there should have been something more someone else could have done to make sure that it did not get out in the first place, and sometimes there is. If they had only tested that one more scenario or entered the data in this certain way, they would have discovered the bug. If the process was simpler or the tests were better we would not have had the problem in the first place. Unfortunately, you can say this till you are blue in the face and those sneaky little bugs will still find a way to get through to your customers. As long as they aren't huge, database destroying, data eating bugs, then it is unfortunate, but it is not the end of the world so why treat it that way. It's no one's fault (or perhaps it is everyone's fault if we are considering ourselves a team), it's just something that happens and in this business, you had better get used to it because it will continue to happen forever no matter how many tests or how simple the process.

So how do you get around this attitude that is adopted every time release season is upon us? I don't know. Do we really want to? Maybe we just care too much about trying to make a good product for our users that we are upset when it has problems (even if they are small and only one person out of a thousand noticed). Or maybe it's just frustration from going through the same process over and over and nothing ever really getting any better (except the type/size of errors that are getting through). I guess all we can really do is suck it up and try to tolerate each other as much as possible until all the updates are done. Then we can relax again and get ready for the next round.