Preparing a structured documentation project
"Information is accessible knowledge"
Knowledge is a precious and undervalued resource, yet without knowledge it is impossible to create high quality documentation.
Before the value of knowledge can be realised it must be converted into information and that information must be made accessible to the documentation process.
However, knowledge alone is not sufficient. Care must be given to ensure that the information is delivered to the user in an appropriate, consistent and efficient way.
The following basic steps are essential to give the best results:
Step 1 – Identify the sources of your knowledge and how it is recorded.
Step 2 – Set up a conversion process to turn the knowledge to information in an electronic format that can be easily accessed using industry standard methods.
Step 3 – Implement a storage and delivery system that provides simple and rapid location of information.
Step 4 – Plan a structure for information units that will allow reuse of material, delivery on-the-fly, and multiple delivery routes to the users.
 |
Document design |
Careful document design can bring benefits and cost savings in many areas.
- Consistent layout and structure makes documents easier to create and maintain whilst improving the reading experience for the user.
- By designing documents with future translation requirements in mind, significant cost saving can be achieved.
- Design for multiple delivery methods avoids repetition and reduces costs.
|
Document Type Definition (DTD) and stylesheet design |
Document structure and presentation is enforced by use of a set of electronic business rules to define a document class. Extensible Markup Language (XML) is an open-standard system that makes use of such a set of business rules by means of a Document Type Definition (DTD) and stylesheets.
A DTD controls the structure of a document class and the relationship between different elements of the document.
A stylesheet controls the formatting of a document class for a given delivery method (PDF, web, e-book, etc. ) linked to elements defined in the DTD. A document class may have several stylesheets, each designed to work with a chosen delivery method.
|
XML authoring and proofing tools |
In order to extract the maximum benefit from a structured documentation delivery system it should be maintained by in-house personnel using XML-aware tools.
For details of proven XML tools, see Tools for structured documentation
