1. Knowing your audience
Writing effective design documentation is all about serving the needs of your audience better. So before starting to write, it’s important for you to know who your audience is, and what exactly they need. Your audience might include product managers, executives, marketers or programmers. Usually it won't be possible to satisfy them all. So it might be better for you to pick the most important group, understand their needs, and then write for them only. If, on the other hand, you prefer to satisfy everybody, it might be better to have a couple of sections for each group created in such a way that other sections don’t bother that particular group.
2. Consistent formatting
An important thing that is often overlooked is the design of the document itself. You would have come across such documents that have excellent content, but their haphazard layout makes it harder for you to study them. The formatting of an effective document needs to be clear and consistent from page to page. It’s not only important for aesthetic reasons, it also ensures that your readers will easily find the things they need to read, and the content will be easy for them to understand.
3. Be smart
While writing and editing your documentation, try to make every statement short and simple. Large-sized paragraphs will look uninviting to your users, so try to convert paragraphs into a list with short sentences whenever possible. Of course there will be situations where you will need to explain something. To ensure you don't get too "wordy" consider incorporating an example in your explanation. And remember, write active voice sentences that start with action verbs.
4. Avoid the absolutes
In most cases, it’s not suitable to phrase guidelines using absolute adverbs. So using terms like 'always' or 'never' should be avoided because usually there will be some exceptions to that 'rule'. Such an absolute way of expression will turn the focus from crafting a great experience to abiding to the rigid rules. Furthermore, readers will start getting habitual of finding the loopholes. This will in turn make them ignore even the most non-negotiable regulations. Actually, the design system is something assistive, not authoritarian. Providing instructions with rationale is more convincing than rigid rules. However, too much rationale will make the readers lose their attention, so a balance is needed.
5. Prefer the positive
Repeated warnings to refrain from negative patterns would put your reader on the defensive. Although there is a lot to tell about not doing something, a good positive communication should also be there to balance it, so the readers don’t find the system oppressive. You would be better off saying ‘Use primary buttons instead of secondary buttons’, rather than saying ‘Don’t use secondary buttons’.
6. Write purposeful headlines
A headline should express a single point that you are trying to assert. Mostly, the readers scan through the headlines to find a keyword related to the problem they are trying to solve.
Every headline has an opportunity to provide the reader with an idea of what they will learn from navigating to the website. You should try to be more explicit to make the content more accessible.
7. Try to empower, not restrain
You should always be mindful that documentation is not something prescriptive. Design Systems are to empower others, not to police against them. Using the Design System as a hammer will make everything look like a nail. Deviations from the established standards are welcome if they have merit. Intuition is a muscle memory that needs to be respected.
8. Add charts and diagrams
Charts often help compare different potential options. Diagrams, as compared to text, usually make it easier and quicker to understand things. Many apps are available to assist you in creating charts and diagrams, such as Google Drawings.
9. Have a partner
No great book or work is usually written without a partner. The design documentation should be no different. You should have someone periodically review the drafts of your design documentation. It would be great if this editing assistant is a teammate who is already familiar with the project and design. Don’t check in with him at the end of your work, rather he should be a regular part of this process. He should be reviewing with you things like: good design description, coverage of all key points and if things are clearly organized. It will be easier to correct the issues with your content or organization scheme if you find them earlier.