Style guides for software documentation
If you are a software developer, and if you need to write an online help system, reference manual, or user guide, where do you start? We recommend these style guides as a starting point:
- Read Me First! A Style Guide for the Computer Industry. Sun Technical Publications, 2003. ISBN 0-13-142899-3. This is the best practical guide that we know of. It deals with general principles.
- Microsoft Manual of Style for Technical Publications, Third Edition. Microsoft Corporation Editorial Style Board, 2004. ISBN 0-7356-1746-5. This focuses on terminology.
- IBM Style, November 2006 (http://www-03.ibm.com/easy/page/1387/$File/IBM_Style.pdf). This covers hardware, software, mainframes, workstations, and other areas of the IBM business. It gives general editorial advice.
- Apple Publications Style Guide, January 2006 (http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2006.pdf). This describes style and usage of Apple terms, including user interface terms. It includes guidance on glossaries, indexes, and writing for an international audience.
- The Missing Manual Authors' Guide (http://missingmanuals.com/author_guide_v3.pdf). This is for authors who write for the Missing Manual series. It contains useful general advice.
Other excellent books are available, but they are designed for professional technical communicators. We think that the style guides in the list are the most suitable for people who are not professional technical communicators, but who need to produce software user documentation as part of their work.
General style guides
For technical writing in general, a good free download is NASA SP-7084 Grammar, Punctuation, and Capitalization (http://stipo.larc.nasa.gov/sp7084/). The document was written for technical editors, so it may be heavy going for people who are not in the profession.
For excellent general advice, see:
- The Oxford Manual of Style
- The Chicago Manual of Style
- The Elements of Style, William Strunk (free to view, www.bartleby.com/141/)
See also ![]()
Language style guide for software developers
Publicly available IT standards (free download, http://isotc.iso.org/livelink/livelink/fetch/2000/2489/Ittf_Home/PubliclyAvailableStandards.htm)