Documentation is something that is usually only appreciated when there is a problem and you need answers quickly. In this article, we will go through the reasons why writing documentation for your WordPress assets is important to your practice as a WordPress developer and the quality of the themes and plugins you ship.
Why is documentation important?
Keeping an updated set of documentation about your projects, assets, or products is important for many reasons.
First, it’s a common experience looking at something that you made 2 months ago and haven’t touched since, and having no idea what it means. When you develop it you have it all inside your head but that understanding won’t be there in the future. So either using inline code comments or writing plain text notes in Markdown, goes a long way in saving your future self from confusion.
Second, keeping your assets documented is helpful for other WordPress developers. And this makes sense even if you are a lone freelancer (you are bound to collaborate with other people at some point). They will either need to use those assets or will be asked to maintain them and/or update them. It is very frustrating having to use undocumented code that is written by someone else, who is not around to provide support or explain some difficult bits.
Finally, documentation adds that “polished” look to your products and your customers will love you more.
5 principles for effective documentation
Technical writing is a discipline on its own and it’s used to communicate technical information in a clear and unambiguous manner. (Not limited to computers alone, lawyers and doctors, for example, also use their own technical language). For that reason, a document that is considered technical writing usually follows a certain style and obeys a set of rules.
Let’s go through the 5 most important so that you can write effective documentation for your products!
- Prefer using fewer words than you would normally use in your writing: Every word should have a purpose. Be direct and simple. Documentation is usually sought after when a person is in trouble and wants to quickly find a solution. For example, a sentence like “Failure to destroy Object Q will introduce memory leaks” is preferable than “Failure to destroy Object Q will cause the introduction of memory leaks”.
- Prefer using active voice instead of passive: “Click the button on the top right” instead of “The button on the top right needs to be clicked”. Using an active voice clears any ambiguities on who does what. Passive voice is only used when you need to focus on the object, rather than on the subject (for example, Pressidium’s Platform is built with security in mind).
- Use descriptive language when you need to describe concepts, and imperative when you need to describe a step-by-step procedure (like tutorials).
- Use bullet-point lists when you need to list things that have no order, and numbered lists when the order of the points is significant.
- Make sure you have tested the instructions yourself, before presenting them!
Documenting WordPress plugins
WordPress plugins are like any other piece of software. They provide a certain functionality, they require installation, and sometimes troubleshooting as well. No matter how simple they are, it’s always a good idea to provide an adequate amount of documentation, because not all users share the same technical expertise.
Try our Award-Winning WordPress Hosting today!
Publishing your WordPress plugin on wordpress.org will provide you with a place to put installation instructions, screenshots, FAQ even a Changelog! Filling them with useful and quality information is key in making your plugin become more popular:
- Write a compelling and useful description that ultimately will make the user download your plugin and visit your website.
- Add annotated screenshots explaining each configuration item of your plugin additionally to the ones showing how your plugin looks in the browser.
- Put questions in the FAQ that are not trite. A good way to discover strange edge cases is to ask a non-computer-savvy friend to use your plugin.
- Have an updated and well-written Changelog. Terse and cryptic one-liners are a big no-no and show that you don’t really care for your users.
- Be sure that your plugin’s code is well commented and follows best software practices and official coding standards.
If you’re stuck and need some inspiration, conduct a small research and see how the text is written in popular plugins that have hundreds of thousands of installations, compared to the less used ones.
Documenting WordPress themes
Documenting WordPress themes is a different matter entirely. The most common problem with WordPress themes is not knowing what section corresponds to what visual element. Not everyone is fluent in CSS:
- Create a hierarchy of all the sections of your CSS, with corresponding descriptions.
- For each section, add an annotated screenshot detailing each functionality, along with a small example. Do not forget to use active voice and imperative language, when showing how to do something that requires the user to follow instructions.
- Use a tool such as css_doc to help you. This generates a JavaDoc style of documentation and can be published.
- Sometimes code comments are not enough and you need to create a Style Guide document for your CSS theme. Style guide documents describe how elements need to look and in what cases they need to be used. They enforce consistency and make collaboration easier as well. See this example by Google.
- Use a CSS framework like Blueprint CSS. This will help you in development by providing you with a set of tools such as a customisable grid, default typography that works, browser CSS reset and much more.
- Again, do not forget to consult the official WordPress CSS coding standards.
Start Your 14 Day Free Trial
Try our award winning WordPress Hosting!
