Style Guide

What Hacker News says

1. anigbrowlNov 2022
   Don't use fake words like 'upskill' when you have perfectly good words like 'improve.' Get them copies of 'the little book' (Strunk and White) and the Economist Style Guide.

   Also, pay attention to grammar, even in headlines: it will significantly improve your teams' output.

   Beta test their output by giving it to first-time or newish users. Be willing to accept harsh criticism, because much technical writing is just really bad writing.

   Minimize the length of sentences. Avoid repetition. Writers who are struggling often just rewrite the same information in slightly different ways, failing to explain their ideas clearly and wasting readers' time.

   Humor and flair are good and help to make a good text memorable, but can also make a bad text annoying.

   Pay attention to layout and pagination. Many technical documents are just read online by scrolling or consulted only occasionally, but for a large project some people are going to want hard copies, and they're the most likely to be your future power users.

   Fonts, whitespace, heading weight etc. matter a lot. O'Reilly books owe part of their good reputation to their visual harmony. Packt also do good layouts.

   By contrast, I'm reading a book from Apress at present and the body text/code fonts are too large. This makes it tiring to read: I am constantly flipping back and forth to refresh context because nothing fits on a single or double page. I've noticed the same complaint from buyers of other books by this publisher.

   This also applies to things like tables of contents, which are one of the few things where repetition is appropriate. There's nothing more annoying when I'm trying to get familiar with some new library than scrolling through long texts of reference material in order to get an overview of what functions are available in each module.

   Try to avoid the trap of a tutorial that stops shortly after 'hello world' followed by in-depth reference material, which often creates a yawning skill gap.

   Between the two, there's room for discursive sections on why those functions exist - outlining some typical use cases, indicating which ones often pair with each other, and alluding to the outside knowledge that an intermediate-level coder or user might need to fully exploit the reference material.

   This is a section where you can explain your design decisions and offer your readers a roadmap for deployment. Without this the reference material can resemble a list of tourist destinations in alphabetical order, with no clues about their geographic relationship.

   Finally, writing is not a one-way process; you need to go through review and rewrite cycles. If you can't edit yourself it stands out on a first reading, even to people who can't articulate why. I delete 50% of everything I write and rework phrase/sentence/paragraph structure constantly. This comment went through 4 revisions and each paragraph was reworked 3 or 4 times while writing. Adding more words is the least interesting aspect of writing.

   Show morethread
2. stblackApr 2021
   That’s a reasonable question.

   I bought The Economist Style Guide shortly after university and I’ve used its recommendations regularly over many years. It’s had a massively positive payback for me. It’s surprisingly versatile advice, whether crafting emails, reports, proposals, or proofing the work of others.

   The Economist Guides are all excellent.

   thread
3. tzmudzinJan 2021
   „Clarity of writing usually follows clarity of thought. So think what you want to say, then say it as simply as possible.” (from: The Economist Style Guide)

   I recommend the whole Guide wholeheartedly.

   thread
4. tzmudzinDec 2018
   > My brain just freezes out whenever I try to write "complicated" sentences which I find extremely irritating.

   Don't do this. Follow "The Economist Style Guide" instead:

   "Clarity of writing usually follows clarity of thought. So think what you want to say, then say it as simply as possible."

   thread
5. tzmudzinDec 2018
   "The Economist Style Guide" is excellent too.
   thread
6. tzmudzinDec 2018
   I can sympathize with you, as I shared the same woes. Don't torture yourself though. Quite often the ornamental form simply hides the lack of intellectual depth in the content. Free yourself from such thoughts and the rest will follow.

   I really recommend "The Economist Style Guide". Please read through it, then read again to see how it was applied to itself (!). Then write a short passage, and revise it to adhere to the recommendations -- don't be surprised if this will need several passes though!

   You will be surprised how much this can improve your writing, but also structure your own thoughts.

   Show morethread