
Ask HN: What style guides are there for technical documentation? - bitofhope
Do you use one at work? Do you prefer or recommend any? What freely available ones are there?
======
wsh
Here are some examples from the computer industry, all available at no charge:

• Apple Style Guide: [https://books.apple.com/us/book/apple-style-
guide/id11618552...](https://books.apple.com/us/book/apple-style-
guide/id1161855204)

• Google Developer Documentation Style Guide:
[https://developers.google.com/style/](https://developers.google.com/style/)

• Microsoft Writing Style Guide: [https://docs.microsoft.com/en-us/style-
guide/welcome/](https://docs.microsoft.com/en-us/style-guide/welcome/)

I’ve found earlier editions of Microsoft’s guide to be helpful when writing
about user interfaces on the Windows platform.

Other industries have their own conventions. For example, the maintenance
manuals for commercial airplanes are often written in Simplified Technical
English ([http://asd-ste100.org/](http://asd-ste100.org/)), and the Securities
and Exchange Commission has published a _Plain English Handbook_
([https://www.sec.gov/pdf/handbook.pdf](https://www.sec.gov/pdf/handbook.pdf)).

There are many other style guides; some are listed on the Wikipedia page:
[https://en.wikipedia.org/wiki/List_of_style_guides](https://en.wikipedia.org/wiki/List_of_style_guides)

Your team or organization may also need to develop its own style guide, to
standardize the names of your products, features, concepts, user interface
elements, and so on.

------
devchix
I have the same question, I'm writing a whitepaper (a useful one, with how-to
steps things and supporting code), and I cast about looking for a style guide
and format for "whitepaper". Imagine my surprise when I found a site from
someone who calls himself "the whitepaper guy" \-- he writes whitepapers for
hire, for anyone, any business. I'm made to realize it's marketing under a
veneer of tech information exchange.

What amounts to _genuine_ tech exchange these days, as it appears to me, are
mostly PowerPoint presentations at conferences. The formal docs are man pages,
and probably RFCs, the informal docs are some guy's blog or a single blog
page. The project's README.md are helpful as well but they conform to the
individual and not any style. Serious tech papers conform to scientific and
research publication style, and even then style guide has more to do with
citations. There's nothing standard and easy to reach for in the business-
technology intersection.

------
giantg2
This varies from company to company for the most part. You have some
standardized formats such as business process maps and use-case diagrams. I
can't remember the name of the free tool we used in my BPM class, but there
are tools out there that follow a standard.

My recommendation is to find documentation for an existing system that you
find helpful and easy to understand, then use that as an outline for creating
your documentation.

~~~
minnca
I've also found that it's more useful to use a good doc as an outline for your
own documentation than to start from scratch + style guide. Using a good doc
as a guide can help you develop your own documentation style – you can figure
out what works and doesn't work for you.

Style guides can be great in the right context, but I think focusing on them
too much can take away from the most important part of documentation – the
content.

~~~
minnca
That being said, Microsoft and Google have decent, publicly-available tech
writing style guides: -Microsoft: [https://docs.microsoft.com/en-us/style-
guide/acronyms](https://docs.microsoft.com/en-us/style-guide/acronyms)
-Google:
[https://developers.google.com/style](https://developers.google.com/style)

------
asicsp
See also [0] which was discussed here on HN [1]

[0]
[https://www.divio.com/blog/documentation/](https://www.divio.com/blog/documentation/)

[1]
[https://news.ycombinator.com/item?id=21289832](https://news.ycombinator.com/item?id=21289832)

------
pytel
I think one should ask who the audience of the technical documentation is.

Is it the practitioners who will use the technology in the wild? Or do you
want to sell your technology to the CTOs and technology scouts? A whole
different format and content might be chosen in case you would like to receive
a thorough feedback and review of your technology (RFC).

