Content analysis

The term content analysis describes a process in which you review existing documents to understand how they are designed and what implicit structure they contain. Begin your analysis by making a list of the documents your organization produces. Your list might include user guides, reference guides, white papers, tutorials, training manuals, and online help. Make a list of the major components for each document type. For each component, list whether the item is required, optional, and how often it occurs in that document. The following table shows a high-level analysis for a book:

Component

Requirement

Occurrence

Front matter

Mandatory

1

Table of contents

Mandatory

1

Preface

Optional

0 or 1

Chapter

Mandatory

2 or more

Appendix

Optional

0 or more

Glossary

Optional

0 or 1

Index

Mandatory

1

For major components, such as lessons (for training manuals) or chapters (for books), work your way down the document hierarchy into smaller and smaller chunks, until you reach the bottom level of the hierarchy.

You must do a content analysis for every document type you want to create in your structured envi­ronment. Once you have developed a content model for each document, you can look for opportu­nities to refine the model and reuse names. For example, suppose that a Help deliverable consists of topics and the chapters in a book also consist of topics. If you create a Topic element that is usable for both printed and online materials, you can minimize the number of elements in your structure definition and perhaps reuse information in both output formats.

Printed Topic

Online Topic

Combined Topic

Topic

Topic

Topic

Title

Title

Title

Para

Para

Para

Steps

Steps

Steps

Can contain Para, List, Table, Graphic, Note

Can contain Para, List, Table

Can contain Para, List, Table, Graphic, Note

 

RelatedTopics

RelatedTopics

It’s unlikely that your documents are perfectly consistent. You need to decide whether to create a structure that is loose (allowing many variations) or strict (very few variations are permitted). You will have problems at both ends of the spectrum:

A very loose structure is quite complex, and can be difficult to maintain because so many vari­ations are permitted.

A very strict structure may disallow element combinations that are needed.

It’s very difficult to find the right balance between these two extremes. One approach is to allow vari­ations only where they add value.

note:   A similar problem occurs when creating unstructured FrameMaker templates. You want to minimize the number of tags that must be maintained while providing all of the tags that are needed to create your content.

Once the analysis is complete, you can decide whether to use an existing structure or to build your own. Numerous XML implementations are available; DocBook and the Darwin Information Typing Architecture (DITA) are specifications used for technical documentation. Standard structures are also defined for military documents (mil-specs or mil-standards), aircraft maintenance manuals, and others. The following table describes some of the factors that influence whether you will use a standard specification or build your own structure.

Use a standard

Build your own

You are required to deliver content that follows the standard. For example, many U.S. military contractors are required to deliver documentation that follows a published standard

You want to create a structure that matches your content analysis precisely.

Your content requirements closely match an existing structure. You only need to make minimal changes to the standard structure.

Your content analysis indicates that your information does not match existing structures very well.

You do not want to spend a significant amount of time building a structure, and you are willing to change the organization of your content to fit it into an existing structure.

The structure needs to match the content precisely.

A longer implementation period is an acceptable cost to ensure you can build exactly what you need

You do not have the technical expertise or resources available to build your own structure.

You have resources available, whether in-house or as consultants, who can build the structure.


September 30, 2016

Legal Notices | Online Privacy Policy