Making Every Page Page One

By Kourtney Short, STC Member

The ideas that Mark Baker shared in his Every Page is Page One presentation on February 13 are at once practical and exciting. He brings together ideas from usability, e-commerce, computer science, psychology, and his own extensive experience as a technical writer to suggest a better way to structure topics and documents.

When I write, I carefully sequence books and online help so that each topic builds on the last. When I use software, cook, renovate, or do almost any other task you can think of, I google until I can get what I want to done. Finding EPPO topics in my search results would certainly encourage me to look to the official documentation more often.

It’s never easy to convince a documentation team or organization to restructure its documents. Mark Baker’s presentation gave lots of reasons why it’s worth the effort. I liked that he didn’t gloss over the difficulties of bringing about the change on tight deadlines and in resistant organizations. (And reading his book gave me even more ideas.)

I look forward to writing some Every Page is Page One topics of my own.

You can see the slides from a presentation similar to the one that Mark Baker gave on February 13 on Slideshare.


About the author
Mark Baker is a Content Strategist and Structured Writing expert, and author of Every Page is Page One: Topic-based Writing for Technical Communication and the Web.

Linear Versus Agile Documentation Lifecycles & Best Practices

By Anuradha Satish

As a technical documentation specialist, I have created documents for a variety of business purposes – procedure writing, requirements and specifications for system enhancements, training and development, use and test cases, release notes, white papers, and so on.

In my experience, every documentation project needs a customized workflow, depending on time, budget, and team constraints. In general, project workflows can be classified into one of two types: the Linear and Agile models.

Linear Model

Traditional linear workflows tend to include processes that follow what is commonly known as the ADDIE principle:

• (A) Analysis – Preliminary discussion and deciding the project scope
• (D) Design – Preparing a detailed documentation plan
• (D) Development – Devising the template, style guide, and keywords
• (I) Implementation – Producing content
• (E) Evaluation – Review and approval

The following flowchart is an overview of a linear documentation workflow:

(Click to enlarge the image)

While the time-tested ADDIE methodology has many clear advantages, it has one distinct weakness: the potential for last-minute ugly surprises.

For example, if limitations of the documentation plan or template are discovered during the Implementation phase, the content creator is left with little choice but to go back and pretty much start over from scratch. The Review phase only begins after the entire content is produced, which requires the reviewer/approver to allocate a large chunk of time and effort to go through the entire document at one go. If the reviewer is not satisfied with the product, the entire process has to be repeated to identify the problem areas.

Agile Model

The limitations of a linear model can be overcome using an agile approach, where development occurs in phases after periodic review and feedback. It is an iterative process and the document is constantly evolving.

Many product development lifecycles have switched to an agile methodology. Modern software applications are often created using this iterative process where the client is equally responsible for providing effective and timely feedback to ensure that the end result is user-friendly and meets business objectives.

When product documentation follows an agile life cycle, it could result in effective communication that is churned out in a regular and timely manner.

A high-level process workflow in an agile environment would look something like this:

(Click to enlarge the image)

As the flowchart illustrates, more versions of a single document are created as compared to an ADDIE approach. The agile method ensures that new product functionality is documented and updated over time. Assessment and feedback are on-going processes, so it eliminates the need to review all content at once and ensures a thorough check.

However, if content producers jump into the writing stage expecting the best results to come only from review or client feedback, there are bound to be more iterations and document versions, thereby increasing time and cost for the company. With no tangible target to achieve, edits and revisions can simply go on and on, delaying SLAs and project completion dates.

Best Practices – A Hybrid Approach

Neither the ADDIE model nor the agile workflow on their own can be ideal in all situations. Analyzing the business need will drive the most suitable methodology. Consider two crucial questions when deciding on the workflow method:

1. Is the company prepared to invest money, time, effort, and resources on revisions?
2. Can the deadline be stretched?

The nature of the document or product could also point at the best-suited development method.

For example, when developing a new document from scratch, following an agile method allows the product to evolve as required over time. But when the end product is an update to an existing version, the linear method is more suitable as the proof of concept is ready to guide Implementation and Review phases.

Applying one critical stage of an ADDIE approach to any agile environment can make the latter as accurate and flawless as practically possible: Pre-development planning. A comprehensive document plan detailing possible topics, reviewers, approvers and target dates can help speed up the documentation process and result in fewer revisions.

A pre-planned agile workflow can bring out the best of both models as follows:

(Click to enlarge the image)