How to Live in an OOD Dream - Part One

Related Posts:
How to Live in an OOD Dream - Part Two
You're Awesome - Tell Me More - OOD Part 3
OOD (Object-Oriented Documentation

---

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:

1. concept
2. 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.