Hacker News Reader

Comment by rodionos | Hacker News Reader

We adopted a set of formal guidelines [0] for our database docs, based on Google Developer Guide [1], and automated the checks as much as possible with linters [2].

The checks cover spelling, markdown formatting, broken links, and grammar/style. For instance, we specifically reject hostnames, domain names, IP addresses, person names, phone numbers unless it's on our Example List[3], which itself is largely based on RFCs.

[0]: https://axibase.com/use-cases/tutorials/workshop/technical-w...

[1]: https://developers.google.com/style/

[2]: https://github.com/axibase/docs-util

[3]: https://axibase.com/use-cases/tutorials/workshop/technical-w...

View on HN

Not to nitpick, but as long as I noticed it I thought I'd share:

> Replace "i.e." or "e.g." with "for example".

e.g., means "for example" but "i.e." means "that is", sort of a one-to-one correspondence. E.g.,

Many places make cheese, e.g., Wisconsin, but only one makes that perfect, crystalline, salty, slightly umami yellow gold that I love, i.e., Parma.

A good reason to avoid i.e. and e.g. is that many people doesn't know the difference.

Thank you for sharing these! I manage our internal documentation and one of the biggest challenges (aside from outdated documentation) is making sure that people write accurate docs. I gave up enforcing strict style, formatting, and word usage guidelines. At this point I'll accept anything in any format, and I just clean it up myself later. But maybe I just haven't been presenting the guidelines in a simple enough way, as you have.

This book, "Technical Documentation Basics: How to Write That F*ing Manual" was a great jumpstart resource for me, in helping break some bad habits about word tense, case, and that sort of thing. https://www.amazon.com/Technical-Documentation-Basics-essent...

I like your list of blacklisted words!

I like the idea of CI to enforce it :) I'm tempted; I wonder what the GP uses for that.

We use Travis CI for checks as well as github and travis webhooks to deliver warnings to specific committers who need to fix the errors in a particular PR. Scheduled Travis CI checks send alerts to the general channel if the master branch starts failing.

I wonder how well this works. Word blacklists tend to be very crude tools.

For example, how often must people actively spend effort working around all the blocked past tense forms? How do you express that something used to work differently in a previous version under these restrictions?

"Remember that everything in this guide is a guideline, not a draconian rule."

The context makes it clear that it is future tense which should be avoided when describing system behavior.

Our docs are on github. We enabled Travis CI checks and all commits are now automatically validated with the default and custom markdownlint rules. If the linter finds errors, the committer receives a warning to Rocket chat with a link to Travis CI status page containing errors as well as suggestions on how to fix them.

Reply on news.ycombinator.com