Want to improve your documentation, but not sure where to start?
Whats one of the first things you look at when you look at using a new project? Its likely some form of documentation. Whether it is official documentation, or external blog posts, videos, books, or even code comments. Ideal documentation should contain everything someone needs to get started with a project without having to read the code. In the words of the creator the Perl language, Ken Williams. Documentation is complete when someone can use your project without having to look at its code. B
Documentation structure applies to your documentation as a whole, and to each page. Lets start at the top and work down. There are different types of documentation your project might need. The terms I use to describe them below are just the terms I use, and others use different terms. The explanation of what they are is more important than what you decide to call them is up to you. Documentation types Getting started A Getting started guide is often a starting point with your project. It should
I appreciate that not everyone who writes documentation is a native English speaker, or even if they are, may not understand the best way to write clearly and concisely. Many native English speakers had our last grammar lesson more than 20 years ago, and have learnt the tips and tricks we now use as professional writers recently. There are three important things to remember to justify the time and effort of making your writing more understandable: English is often a default language for technica
Meta discussions on writing