3 ms·
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
by anigbrowl 4y ago
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.