Embedded Files
Documentation
Designing technical content around tasks, audiences, reuse, and the
Documentation Is Part of the System
Documentation Is Part of the System
Technical documentation has to do more than explain how software works. It has to help people accomplish something, which means the structure surrounding the content matters as much as the individual instructions.
I've approached that structure differently depending on the problem. Sometimes the priority was organizing information around the user's task. In other cases, it meant designing for reuse across audiences or creating an authoritative source that could support operational decisions over time.
| The document is the visible output. The system behind it determines how useful and maintainable it will be.
Designing Documentation Around the Task
Designing Documentation Around the Task
For a workflow application used by both internal teams and customers, I organized the user manual around the actions people needed to complete rather than simply documenting the interface screen by screen.
Each procedural chapter began with a Goal, explaining what the task was intended to accomplish, and Prerequisites, identifying what needed to be true before the user started. The procedure itself was followed by Results, making the expected outcome explicit.
The FAQ provided another route into the same information. Users could watch a short demonstration for immediate guidance or follow a cross-reference to the complete step-by-step procedure elsewhere in the manual.
BROWSE THE DOCUMENT
BROWSE THE DOCUMENT
Sample_User-Guide.pdfTask-based chapters defined what the user was trying to accomplish, what needed to happen first, how to complete the task,
and what successful completion should produce.
______________
| Design principle: Organize procedural documentation around what the user is trying to accomplish, not around the structure of the software.
One Source, Different Audiences
One Source, Different Audiences
When different audiences need variations of the same information, maintaining separate documents creates another problem: every duplicated source becomes another place that can fall out of sync.
Designing Content for Reuse
Designing Content for Reuse
For one application, different user groups needed different versions of the manual. Rather than maintaining a separate source document for each audience, I built the manuals in Adobe FrameMaker using conditional tags.
Audience-specific content could coexist within a single maintained source, with conditions determining what appeared in each published version. This reduced the effort required for global updates while also reducing the opportunity for inconsistencies between versions.
| The complexity remained in the authoring system so it didn't have to become a maintenance problem.
THE SOURCE BEHIND THE DOCUMENT
THE SOURCE BEHIND THE DOCUMENT
Adobe FrameMaker conditional tags identified content intended for different user groups within a single maintained source. The colored indicators shown here were authoring controls and did not
appear in the published manuals.
______________
THE PUBLISHED OUTPUT
THE PUBLISHED OUTPUT
enhanced FAQ.pdfConditional publishing produced audience-specific documentation from the shared source
while keeping common content centrally maintained.
______________
| Design principle: When content must appear in multiple forms, structure it for reuse instead of maintaining duplicate sources.
When Documentation Becomes the Standard
When Documentation Becomes the Standard
Some documentation doesn't simply help people perform work. It defines what correct work looks like.
At LibreDigital, I created and maintained a processing guide used to train new conversion vendors and new team members at existing vendor sites. The guide documented how print periodicals should be processed for EPUB conversion and served as the document of record when determining whether work had been completed incorrectly for purposes tied to marketplace service-level agreements.
The guide was organized around stages of the production process. Each quarter, I gathered updated examples and screenshots from vendor teams. I revised the manual approximately twice a year to keep pace with changes in the production environment and customer requirements.
BROWSE THE DOCUMENT
BROWSE THE DOCUMENT
Sample_Magazine-Processing.pdfThe guide served as both instructional content and an operational standard, providing a shared reference for training, production decisions, and quality evaluation across distributed teams.
______________
| Design principle: When documentation defines correct performance, maintaining it is part of operational governance.
Documentation as Infrastructure
Documentation as Infrastructure
Documentation can play very different roles in a system. What matters is designing it for both sides of its lifecycle: the people who depend on the information and the people responsible for keeping it trustworthy over time.
That changes documentation from a collection of instructions into infrastructure the organization can rely on.
| Good documentation doesn't sit beside the system. It becomes part of how the system works.
_____________________________________________________________________________________
Explore Another Special Project
Explore Another Special Project
Google Sites
Report abuse