top | item 32116703

(no title)

wootest | 3 years ago

Grammar is not the most important thing, but it's hard to exemplify tone and voice without having the common language to talk about them and grammar is that language. I'm guessing the article starts with it because tone and voice is the most universal aspect, not because it's the most important aspect to technical writing. The rest are very hands-on details but that might not apply to everyone.

The two-axis diagram on diataxis is a great way to categorize documentation and all of them have different needs and indeed call for different voices. I have seen a number of projects where the only documentation produced is tutorials or itch-scratching posts for this one thing, and then when a feature changes somewhere you have a mountain of out-of-date information because everything was hard-wired to this combination of dependencies, versions and circumstances (whereas a manual could have been updated quickly and that would be that). And on the flip side, plenty of projects where there is a dense compendium for every detail and it's hard amid all the implementation details of the clustering gossip protocol versioning to find the little list of items you want to know to set the thing up to begin with - linked to the particular sections to read more about installation, configuration, backup, etc.

discuss

order

No comments yet.