←back to thread

262 points jumpocelot | 1 comments | | HN request time: 0.232s | source
Show context
kaycebasques ◴[] No.44523298[source]
Looks solid. My gripe with most technical writing (TW) style guides (this one included) is that they mix best practices with conventions:

* "Best practices": Aspects that tangibly improve docs quality. Usually backed up by experimental data or overwhelming consensus.

* "Conventions": Arbitrary decisions that don't clearly improve docs quality one way or the other, except for the fact that they improve consistency, and consistent docs are easier to use.

When everyone in the room has this shared understanding, TW style guide conversations often go much faster and smoother.

replies(2): >>44523477 #>>44527957 #
1. clickety_clack ◴[] No.44527957[source]
I’ve been on both sides of this, and I’ve come to the realization that it depends on the audience of the writing. It seems like this is for Red Hat authors writing miscellaneous docs for a range of users. Consistency is important there, so that Red Hat seem consistent in their messaging, as a single user could be reading material from many authors. It would look sloppy if the small stuff is all over the place.

Many times, a user receives communication from a single writer. This could be a consulting arrangement, or a small company, or any number of cases really. Those users are probably going to be consistent with themselves anyway, so there’s less need to be as specific on the small stuff. In that case a guide is really just trying to knock off the obvious rough edges in someone’s writing to make sure they’re actually communicating the information.