Rapid Protoyping Documentation

fengor

hi all,

let me share a tale from the beginning of my IT life with you. When i started being an apprentice programmer at an insurance company here in germany, we were shuffled through each department. Supoosedly to learn the workflow of the company and to gain a better understanding about the processes. All in all a good idea, although in practise it-apprentices usually didnt learn very much in the varous departments and where ebing used for computer related tasks that the actual department didnt want to do themselves or didnt want IT to pay for doing it.

One particular department where i was placed as an apprentice had the task of writing an user level documentation for our client stock register. Since they wanted to do it right they made themselves a word template that consisted of two textareas. one big one for the documentation and a small one tot he right for helpful little annotations so that people can scan the right box to find the spot they need quicker. They saved that template and began to write. So far so good. The WTF starts when the first writer reached the end of page1. Since they made jsut textareas, they didnt continue down do page 2 but stopped at the end of the page but this brilliant individual figured a quick way to get around this limitation: save and make a new document for the new page from the template. This was soon adopted to be the way of writing the documentation.

Fast forward a feew weeks or months and IT-Apprentice enters the scene. Meanwhile there are hundreds of pages written, all in one fiile per page. Now the head f the group working on the documentation doesnt want so much files but someone has to combine them in a single file. Surely a fulll working member of his team is paid too much for such a trivial task so the work falls naturally to the it apprentice (programming is obviously about using word ;). So for the next 2 weeks I find myself copypasting page after page into a single huge word document. As you can imagine when i say huge i actually mean HUGE!!!. After finally finishing with the task i present it to the head of the group but is he satisfied? no of course not since that document now takes ages to open. (Did i mention that i proposed not to use 1 huge file but maybe 1 file per chapter or something like that? but who listens to apprentices anyway?). So IT_kid has to find a way to speed up opening of the file. Seperating ist is not an option.

First candidate for reducing filesize are the screenshots. so i ask what image formats they have. The blank looks after that question let me fear the worst and sure enough they are just doing screen captures and pasting them into word. then overlay them with speech bubbles and stuff. With an average of two screenshots per page. just taking the screenshot, copying it into an image software and resizing it and savingit in a compressed format didnt work since word messed up the position of the speech bubbles and stuff and the people of the group didnt want to look at every screenshot again to see if it was correct. so i ended up doing screenshots of sthe screenshots cutting out the actual screenshot and saving it as a bmp (back then paint only understood bmp) And when i finally had every screenshot as a single bmp file WITH the bubbles i bend the it rules a bit and downloaded a batch image convrter fromt he net and transformed all the bmps into png. Then i spend another few days deleting the old and inserting the new...

The document was still huge but loading time came down enough to make it remotely usable. I showed it to the head of the group and he was satisfied... at first at least. Several hours later i was called in his office and hew anted to know why he couldnt change the text in the bubbles anymore. I patiently told him that they are now pwart of the images and stuff since his group didnt want to check the bubbles for correct postioning. Turned out several pages were still work in progress and demanded change etc, so i offered to show them how to do a screen capture cut out the part of the caputre they needed and how to use the image converter but they turned that down. instead i was ordered to reverse the whole process. Luckily i kept a backup of the first files and made myself two easy weeks before copying them back on the server and lcukily be able to leave that departmen since my time there was up.

greetings
fengor

dhromed

Dude.
That's bad.

Praise the incompetent!

marvin_rabbit

Good thing your education has prepared you for a career of Cut-n-Paste.

ammoQ

Writing large documents with word... always a good source for fun and excitement. My company managed to create a word document which was so over-formated that none of the free tools could convert it to PDF, they would either crash or freeze.

snoofle

About 2 years ago, I worked for this person who firmly believed that OLE was the Savior of all things computerized. He had built this 'document', which had an OLE excel spreadsheet, where the cell columns represented 4 'page' columns (left margin, left column, right column and right margin), and each cell row represented the 'paragraphs' in the respective columns (eg: left margin notes, left col text, right col diagram and right margin notes). Of course, each 'cell' was an OLE linked object (paragraphs were word docs, diagrams could be anything (visio, power point slides, you name it), etc.

The whole melange was in one directory with main.doc, but the directory was on a network drive with a slow connection. You can imagine the fun of trying to navigate through this thing.

R_Flowers

@ammoQ said:

Writing large documents with word... always a good source for fun and excitement. My company managed to create a word document which was so over-formated that none of the free tools could convert it to PDF, they would either crash or freeze.

I know several people, professionally and otherwise, who have 2 simple rules when it comes to documents.

If it can be formatted, do it. Italicize, embolden, AND underline it. Change the color. Change the font. Change the size. Add a 'smiley face' graphic in there somewhere. Next line, do the same but make it a different color.
If there's a formatting aspect you can't change, ask IT to make it possible.

KeeperOfTheSoul

One easy way in word of making a large document like that is to create several smaller documents (one for each chapter) then import them all as linked sub documents in a master document.

The bigest trouble I've found with word is it's standard way of working leaves you worrying about the typesetting when you should be working on the content first (normal view and outline mode) followed by the typesetting (print preview). Using this with proper styles set up (create styles during the content based upon logical items then stylise their look later).

Lastly an export to PDF can make viewing the final document easier as it seems to handle on demand loading of only portions of the document much better, it also handles viewing inside a browser much better than word.

But then that's just how I handle any documentation. I did like latex as that was very logical but no co-worker would understand it, the same goes with html.

qbolec

..which again, forces me to recall my favorite part of Word generated HTML:

<![if !supportEmptyParas]><![endif]> <o:p></o:p>

Iago

@KeeperOfTheSoul said:

I did like latex as that was very logical but no co-worker would understand it, the same goes with html.

LaTeX is limited: it's a pile of flakey macros piled on flakey macros, which works very well for typesetting mathematical journal articles in English, but it rapidly gets horribly complicated when you try to do anything like (heaven forbid!) embed a picture or use a font other than the hideous default, and it appears to be essentially incapable of supporting non-alphabetical languages: good luck getting it to display Arabic or Korean, it's "possible" in the same way that it would be "possible" to write a fast, robust, secure, and maintainable application in Javascript.

HTML is a non-starter. Can't even do basic indexing, and the semantics are designed for websites, not documentation.

I've heard good things about DocBook, though.