Creating professional IT documentation is important because it saves time, money and training effort. At Dialog, we have consultants that are equipped with the skills to create clear and precise documentation for every stage of the Systems Development Lifecycle. The four key elements to creating great documents are:
- Knowing the audience
- Consistent styles and templates
- Visuals
- Proof Reading
1. Knowing the Audience
When writing a document, the first thing the author needs to consider is the audience. Who will be reading the document? What information are they looking for? What is their level of experience and knowledge of the subject? Well written documentation for a new system should allow a reader to understand the subject matter with limited prior knowledge. Creating efficient and simple documentation means time and money are saved as extensive training is not required.
2. Consistent Styles and Templates
Templates help to improve the quality of documentation and can make creating and reading documents easier. Well developed templates, accompanied by clear written instructions, can help a project team create both business and technical documents that are of a high standard and, most importantly, can be easily identified as all belonging to the same project, team or organisation.
If a template is used each time a new document is made, the styles and formatting are less likely to be corrupted or to contain out of date information.
Dialog consultants are able to use the expansive collection of templates and reference materials available in the Dialog SAGE knowledge-base throughout every stage of the Systems Development Lifecycle.
Case Study
Recently, a Dialog consultant reviewed a sample of documents for an IT department of a large government agency. The documents were poorly presented and difficult to understand and compare. The consultant worked in conjunction with the director, team leaders and team members to identify what documents were needed. They decided that two generic templates could be used to create reference material and other infrequently created documents.
The consultant wrote a full set of instructions including a base document covering the elements common to all documents and 25 separate task cards covering more specific elements to complement the new templates. The templates and the accompanying instructions were written into a policy mandating that all future documents produced within the section must be created from the clean templates provided.
3. Visualised Simplicity
Presenting information in a ‘text only’ format can detract from the clarity of the content. The following are examples of a few of the many different ways in which information can be better presented:
- Tables
- Flowcharts
- Graphs
- Images and screen shots
- Timelines
4. Proof Reading
The accuracy of the content needs to be checked by someone who has knowledge of the subject matter contained in the content. At this point it is important to ensure that all relevant information has been included in the document. The table of contents also needs to be reviewed.
When the document is completed it needs to be thoroughly proof read, preferably by someone who hasn’t seen the document before. The proof reader should check spelling, grammar, logical flow of content, readability, consistency of writing style and language (especially when multiple authors and contributors are involved), consistency in formatting, and general layout.
Writing effective documentation is not easy. However, using experienced technical writers and following the four tips in this article, you will be able to write better documentation.
