Mixture Posture: OOD (Object-Oriented Documentation)

Showing posts with label OOD (Object-Oriented Documentation). Show all posts

Tuesday, April 7, 2020

CONTENT REVIEW: DO NOT PUBLISH

I didn't set out to write about a mistake I saw on Amazon.com - it just happened.

In fact, until today, I believed that Amazon doesn't make mistakes. Whether it's fair to think this or not, it's what I thought.

In the X number of years I have used Amazon.com, where X = a number that is greater than 1 and less than 100, I had never noticed a blatant mistake.

I know someone made a mistake because the Print Length is 1 pages and the description says 480 pages. I also believe that the [CONTENT REVIEW: DO NOT PUBLISH] text was supposed to be a flag for the publishing system to not actually create this page. You can click this link and go see if it still exists. [CONTENT REVIEW: DO NOT PUBLISH].

I was not browsing Amazon.com to look for errors. I was there because I received this email today, Tuesday, April 7, 2020, at 1:00 AM:

We currently have some of our best-selling Linux books free in Kindle format only right now at Amazon.com until Saturday.

Go to this page to view what they are.

Enjoy and share this email with anyone you think would be interested in learning more about Linux.

P.S. You don't have to own a Kindle device in order to read this book. Just use the Kindle Cloud Reader or download the Kindle app for your PC, Mac, or mobile device.

P.P.S. I wanted to share this resource in the hopes that you can take advantage of it. However, if you don't have an Amazon.com account, then you probably won't be able to download the book. Sorry, there are no other free options available and no PDF copies available.

I clicked the link in the text above and reviewed the list of Kindle books that were available and discovered I am not interested in learning about Linux at this time in my life. Knowing that they are free books and knowing that they are likely awesome, I'm just not interested. I did browse through some reviews of this book and found the review below. I believe that review is worth storing on this blog. At first, I wasn't sure if it was an attempt at humor or not, but then, after re-reading it a couple of times, I came to the conclusion that this reviewer is serious.

Initially, I was put off by the review because of its tone, but then I considered that I would write something similar in a review of a book about Metallica if the author stated on page 1 of the book that Lars Ulrich was born in England. It would be factually incorrect and if I were at a bookstore and picked a book off of the bookshelf or if I were reading a preview of the book on Amazon.com, I would put the book back in its place. Another example might be if I picked up a book about technical writing and on the first page, the author stated that copying content and pasting that content into multiple MS Word files is a sound approach to working as a technical writer. If I were at a bookstore and picked a book off of the bookshelf or if I were reading a preview of the book on Amazon.com and read that gibberish on page 1, I would take a picture of the book so that I could write a review of the book online using the same type of tone as the review above since the author would be breaking the rules of OOD (Object-Oriented Documentation). I would also want to include a picture on my Single Sourcing Rant page located on this blog.

Thursday, February 4, 2016

You're Awesome - Tell Me More - OOD Part 3

It's not about the tool.

While I have my favorite tools for documentation, I realize that, by extension, every technical writer has a favorite tool. The point of these OOD posts has not been to declare some slick slogan at the end like Confluence Rules, All Other Tools Drools. If any of these posts has swayed you to believe that you can't obtain the OOD dream if you use this tool or that tool, you've missed the point. The bottom line concept of OOD is to treat each segment of information as just that - a segment. Segments can be arranged and structured and maneuvered any way necessary. Further, by separating content from presentation, the appearance can be quickly changed to adapt to new requirements.

Here are some links to expand your mind.

Separate Your Content from Presentation

Click this link to read a short summary of this concept. Since the page is part of a multiple step tutorial, the first two paragraphs are the most relevant to the topic: http://www.webreference.com/html/tutorial5/1.html
Click this link to read a short summary about this concept. The In a Nutshell box at the top of the page condenses the concept nicely: http://universalusability.com/access_by_design/document_structure/separate.html

Using Confluence

Click this link to read about the principle difference in approaching documentation that is maintained in Confluence: http://thedetaildept.com/2012/07/31/confluence-is-not-a-word-document/
Click this link to read about the principle of storing content that needs to be used in multiple other places as a reusable “chunk” – instead of copying & pasting that content - to assemble a “topic” or web page. It includes a link to how this idea is used between software systems: http://jodiem.com.au/2011/08/13/the-one-thing-in-one-place-once-rule-using-confluence/

Using Microsoft Word

Click this link to read about the mechanics of setting up documents that split repeated content into smaller documents and to then refer to them in the “main” document: http://www.writersua.com/articles/modular/#The%20Mechanics%20of%20Modularization
Click this link to read about a tool called SmartDocs. I have used the demo version of this product: http://www.thirtysix.net/smartdocs/features/techpubs

More of the OOD Dream - Part Two

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.

How to Live in an OOD Dream - Part One

Introducing OOD

It is the next new buzzword in documentation and content creation: OOD.

I created this term after I came across this definition of Object-Oriented:
|
An approach to structuring software applications. Instead of thinking of an application as a process with steps, we think of it as a set of objects that exchange messages. Now the dominant approach to software development. Java and Visual Basic are object-oriented software development languages.

Source: http://www.appian.com/bpmbasics/bpm-glossary/?letter=o
|
As a professional communicator, I embrace this definition. I usually see "Object-Oriented" followed by a noun, such as "Object-Oriented Programming." Thus, tweaking the above definition and incorporating the noun it describes, I offer the following slightly tweaked definition as the guiding principle of my work in the technical writing profession:
|
An approach to structuring technical documentation. Instead of thinking of technical documentation as a collection of procedures with steps, we think of it as a set of objects that communicate information.

|
Theories are like standards - there's so many different ones, all you have to do is pick one. The question always comes down to how does the pie-in-the-sky theory relate to daily - and I'll say it - grunt work when your duties are to write documentation.This post begins to build the bridge between the theory of OOD and the translation of the theory into practical terms.

First of all, this is not a new thing for me. For roughly the last 4 years, I have subscribed to the theory that writing documentation - whether it is for a Disaster Recovery manual or software online Help - is not done the ODD way when the content is thought of as a "document" that is a silo of content, especially if that content is also in other documents.

In my mind, "documents" have a subliminal context that it is a stand-alone container of information. Traditionally, a document can be a Microsoft Word file, a Dreamweaver HTML file, an InDesign file, or any other file that writers use to store the information that is ultimately distributed to the audience. I'm adding the subliminal context that content in a document is not shared between another document. For example, let's consider a real-world environment. For the same system, there's a Quick Start Guide and a User Guide. The Quick Start Guide is a brief - probably no longer than 3 pages, preferably 2 pages - of what a user has to do in order to set up the system. The User Guide is a collection of all the tasks a user can complete. Because the Quick Start Guide and the User Guide are about the same system, there is overlap in the content because both documents include two types of information:

concept
task

In the "documents" paradigm, these two guides are considered separate entities. They are maintained separately. If there is information that is identical between the two, it is written in either of the guides and then pasted into the other. Because the Quick Start Guide is shorter, sometimes it is necessary to remove content to adhere to the page length. What this does, then, is create two versions of the same content.

That is bad.

In an OOD environment, there is a single source of the content. That content is then tagged for the intended output. For example, a conceptual paragraph is only going to be in the User Guide so it would have a "User Guide" tag applied to it.

By the way, Help Authoring Tools (HATs) have done this for years. Flare and my personal favorite because I earned a MVP Certificate for it - RoboHelp - have this functionality. What I'm advocating is that technical writers verbally call this mentality "Object-Oriented Documentation" or "OOD." Before I was laid off, I used Confluence in the way this post describes. Our team came up with the idea of including screenshots in an expand / collapse section. We reasoned that doing so would serve both those users that know what they are doing and don't need the screenshot and those users that don't know or are unfamiliar with the tasks they are doing and do need the screenshot to verify that they are in the right place. I know our department didn't invent this methodology - I'm not claiming we did.

The beauty of this OOD mentality is quite simply awesome. When there was conceptual information that needed to be in multiple places, we created a page with just that content and referred to it from the pages that needed to have it. In this way, both written word and screenshots that were referred to in many places could be updated by simply updating the page that was referred to by those other pages.

Search This Blog