TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
I have three parts to my Documentation Conventions:
-font use (useful in conjunction with the BNF section)
-icon use (mainly for completeness, but it is nice to distinguish what a
warning means instead of a caution, as well as defining what
platform-specific icons indicate)
-flavor of Backus-Naur Format (BNF) use
The most important is the BNF use. There are so many flavors in use in the
world that it is handy to choose one and document it. If I wasn't writing
API or command line tool documentation, the entire conventions section might
One Techwr-l respondent states that she doesn't include a conventions
section because no one reads it.
If we always took that extreme position, we wouldn't write documentation,
because no one reads it :)