Tips for Writing Manuals

Rule number one : there are of course no rules.

These tips below are from my own experience in writing manuals. My background is largely informed by workshops I have done in free software tools, especially streaming tools. This experience informs the structure and content of the manuals I write. Feel free to ignore these tips!

Write

When writing a manual just write down everything you know in one continuous stream of thought. Don't worry about the structure and language too much, just get the information recorded. If you explaining how to use a software or how to install it then make sure you have the software in front of you and write the information step by step, as you use the software.

Reduce

Once you have written what you know go back through the material and pull it into shape, reducing the material as much as you can until you have nice clear statements and explanations. The beauty of writing a digital manual is that there is always the opportunity to improve the work, so give yourself some time and re-read the material at a later date (you might be lucky and someone will improve it for you). More often than not when you revisit the material you will see a way to improve what you have written.

Reuse

The design of FLOSS Manuals is influenced by free software practice. A principle of free software is that you should write reusable code. If you write code in this fashion it can easily be implemented in other software, saving the programmers a lot of time and heartache.

This is also true for writing good documentation. Write your explanations in reusable chapters. If someone else can use what you have written in another manual it will save them a lot of work.

One good way to assist this process is to write short chapters on specific topics. Once you have written something, see if you can break it into smaller reusable sections. In the repository you would then create a new chapter page for each section. In this way others can include those chapters in their manuals.

Try reading what you have written and imagine it being included in another manual. Would there be anything that would appear odd or out of place? If so this might have occurred because you have written something that is specific to your manual. Your explanation might, for example, include a reference to another chapter you have written. If so then try and re-write it so it could be reused in another manual.

Explain Jargon

Its a good thing to use jargon as it is the language of the expert and if people don't know the terms they will be excluded from this discourse. However it is very necessary to explain jargon clearly when you use it. However, don't drown the reader in too much jargon, you can drip feed them slowly so they don't feel overwhelmed.

Additionally, if there is not a glossary in the manual you are writing then consider including one, either from another manual on a similar topic, or write your own. This is however, not a substitute for good 'in line' explanations of terms.


LOGIN REGISTER Search GUIDES HOW TO EDIT GOOD MANUAL WRITING SYNTAX GUIDELINES	Tips for Writing Manuals Rule number one : there are of course no rules. These tips below are from my own experience in writing manuals. My background is largely informed by workshops I have done in free software tools, especially streaming tools. This experience informs the structure and content of the manuals I write. Feel free to ignore these tips! Write When writing a manual just write down everything you know in one continuous stream of thought. Don't worry about the structure and language too much, just get the information recorded. If you explaining how to use a software or how to install it then make sure you have the software in front of you and write the information step by step, as you use the software. Reduce Once you have written what you know go back through the material and pull it into shape, reducing the material as much as you can until you have nice clear statements and explanations. The beauty of writing a digital manual is that there is always the opportunity to improve the work, so give yourself some time and re-read the material at a later date (you might be lucky and someone will improve it for you). More often than not when you revisit the material you will see a way to improve what you have written. Reuse The design of FLOSS Manuals is influenced by free software practice. A principle of free software is that you should write reusable code. If you write code in this fashion it can easily be implemented in other software, saving the programmers a lot of time and heartache. This is also true for writing good documentation. Write your explanations in reusable chapters. If someone else can use what you have written in another manual it will save them a lot of work. One good way to assist this process is to write short chapters on specific topics. Once you have written something, see if you can break it into smaller reusable sections. In the repository you would then create a new chapter page for each section. In this way others can include those chapters in their manuals. Try reading what you have written and imagine it being included in another manual. Would there be anything that would appear odd or out of place? If so this might have occurred because you have written something that is specific to your manual. Your explanation might, for example, include a reference to another chapter you have written. If so then try and re-write it so it could be reused in another manual. Explain Jargon Its a good thing to use jargon as it is the language of the expert and if people don't know the terms they will be excluded from this discourse. However it is very necessary to explain jargon clearly when you use it. However, don't drown the reader in too much jargon, you can drip feed them slowly so they don't feel overwhelmed. Additionally, if there is not a glossary in the manual you are writing then consider including one, either from another manual on a similar topic, or write your own. This is however, not a substitute for good 'in line' explanations of terms.

GUIDES

Tips for Writing Manuals

Write

Reduce

Reuse

Explain Jargon