How to Live in an OOD Dream - Part Two
You're Awesome - Tell Me More - OOD Part 3
OOD (Object-Oriented Documentation
It was a nightmare to track.
It was a nightmare to update.
Documentation was maintained as Word files. We had one area of the system that had a 5-7 page section written about it. Those 5-7 pages were in - let's say - 10 different User Guides. When there was a change to that section, the change was written, and then I, or someone in the department, had to open each of those 10 different User Guides and manually copy the rewritten text and paste it into each Use Guide. Yes, that was done 10 times - once for each User Guide.
It wasn't just at my most recent employer. For a dozen years, I worked in an environment where the amount of copy and paste would stagger anyone. And it wasn't just text - screenshots weren't even maintained as separate chunks of information. A screenshot was taken and then pasted into a document. If that screenshot changed, I had to remember all the different places it had been pasted. I was able to do this work only because I created all of the documents and, like a database, I expanded the connections between documents in my brain. I also used a tracking document - also a standalone collection of information - to help me remember what changes had been made.
But there's another aspect of OOD that I haven't even mentioned. It's the aspect of separating "Content" from "Presentation". Andrew Plato, a former member of the Techwr-L list, used to go on rants about how the most important aspect of technical writing was the content, not how pretty the text looked. I think following the principle that content is tagged so that its appearance can be changed by a single change to a file - whether it is a CSS file or a Microsoft Word template - is tremendously helpful. It's too easy to get bogged down in whether UI elements should be bold or italic or in a different font or size. If the content is tagged as, say, a "check box" and all content about a "check box" have that tag, you can define what formatting should be applied to that "check box" tag. I like to use the example that you are writing a document and decide that all references to a check box should have bold and italic applied to it. Then your boss comes by and states that customers are having a difficult time with the way the document is formatted and requests that all references to a "check box" should not have bold and italic, just bold.
When your content is separate from your presentation, this is an easy request. You edit the file that stores the formatting information and all references to a "check box" are instantly updated per your manager's request. When your content is not separate from your presentation, this can potentially be a very long and complex request to complete. You may have to search through many documents to manually find the references and apply the change.
No comments:
Post a Comment