Earlier quoted context omitted.
https://www.btb.termiumplus.gc.ca/tpv2guides/guides/pep/inde... The suggestion is to never separate a subject from a verb or a verb from its object
Hey, thanks for that! Proper comma (and semicolon) usage is always a challenge for me. I decided to develop the habit of the "Oxford Comma," but I don't think I have it down, yet. It also seems to be "un-American." American English does not like commas.
Ask HN: How to level up your technical writing?
131–140 of 162 posts
Re: Ask HN: How to level up your technical writing?
#132Earlier quoted context omitted.
> It's really hard to find fiction books, that are less than 500 pages. To play editor for a moment — your sentence needs no comma, and it’s easy to find fiction books with fewer than 500 pages ;) Was a clause omitted?
https://www.btb.termiumplus.gc.ca/tpv2guides/guides/pep/inde... The suggestion is to never separate a subject from a verb or a verb from its object
Re: Ask HN: How to level up your technical writing?
#133Docs for Developers: An Engineer’s Field Guide to Technical Writing
Re: Ask HN: How to level up your technical writing?
#134Earlier quoted context omitted.
Once downloaded a copy of Hound of the Baskervilles, broken into chapters as separate files. Each chapter was almost exactly the same length, within a few hundred characters, showing that it had been serialized first and chapters were sized for publication.
I'm trying to remember if it was Dumas, but some French author was reputedly paid by the word, so all their dialogue is incredibly drawn out ("I have a question." "What is the question?" "It is, as you might expect from me, a simple question." "By all means, please, present me with the question, that I may resolve your puzzlement." ... etc.).
Historical novels are often big offenders. Like the author has done a ton of research, not a bad thing, but can't bear to leave any of it out, and there is no editor to say that's too much, people don't need to know how big the potato patch at the Palace of Versailles was.
Re: Ask HN: How to level up your technical writing?
#135Earlier quoted context omitted.
These days shorter fiction is almost always published as part of a collection, unless you are selling on line or self publishing in print.
Is this in response to the wrong comment? I'm giving an example of the opposite of what you're saying.
I will mention that I highly recommend Simenon's writing, Maigret series and others. He's a fine writer. The TV series with Michael Jambon is excellent. The Maigret stories are the right length to turn into an hour show without losing too much of the interesting details.
Re: Ask HN: How to level up your technical writing?
#136Earlier quoted context omitted.
Is this in response to the wrong comment? I'm giving an example of the opposite of what you're saying.
What I meant was that books like the Maigret novels probably wouldn't be published as free standing books, but packed into collections, say three or four of them together, to get closer to the magic 500 pages. I will mention that I highly recommend Simenon's writing, Maigret series and others. He's a fine writer. The TV series with Michael Jambon is excellent. The Maigret stories are the right length to turn into an…
Re: Ask HN: How to level up your technical writing?
#137Tech writer here. The absolute, invariable first rule in tech writing is to know your audience. Understand not just their technical problems but take the time to empathize with why they have these problems in the first place. Tech writing isn't about documenting, it's about finding the best way to explain something to people so they can solve their problems. Oh, and use an editor (the human kind, not the digital kind…
> Oh, and use an editor (the human kind, not the digital kind.) This is so important (IMNSHO). It's fairly obvious, that editors are becoming a "lost art." My mother was a scientific editor, and she was brutal (she edited some of my work). It's really hard to find fiction books, that are less than 500 pages. I read a story about Stephen King. Apparently, he hates being edited (most writers don't like it). When he was…
Compare "Foundation" with "Foundation and Earth" or "Foundation's Edge". Or "The Philosopher's Stone" with "The Order of the Phoenix". The former were well-edited and succinct. The latter were overly long, in some cases sorely repetitive with large amounts of padding, and a good editor could have cut them down by at least half without losing much.
And let's not even get into Robert Jordan...
Even the best authors need an editor.
Re: Ask HN: How to level up your technical writing?
#138Re: Ask HN: How to level up your technical writing?
#139As the top poster mentioned, "know your audience". You must pitch your material at the right level for the reader. This doesn't mean dumbing it down. It means not including material which isn't relevant for the discussion at hand, and including material which is relevant. As an example, in some internal documentation for end users, one programmer wrote up details about the I2C bus number and addresses and details of some parts on the bus. Not suitable for user documentation, it's just not relevant at that level. They could have mentioned what the user needed to know e.g. configurable options within the application and their effects upon the device function and behaviour. That could be quite detailed, but it doesn't need to include unnecessary detail about the hardware details.
Structure your documentation to introduce concepts that build on each other in order.
For each topic, write an introduction to provide an overview of the concepts and what you will cover, then go into details with examples in logical order, and then wrap it up with a summary and any relevant conclusions at the end. You're taking the reader on a journey with you through some complex topic and you need to treat it like a story with a narrative. It all needs to fit together as a whole, not just a collection of disjoint factoids.
Have a read through various technical books and see how others structure their writing. See how they break everything down into (volumes!), chapters, sections, subsections and paragraphs, and then look at how you can take the system you are documenting, and break it down in a similar way. In many ways this mirrors breaking down a complex set of requirements into applications, libraries, data structures and functions, and depending upon what you're writing about there may be some commonality there. But you aren't just describing the nuts and bolts, you're describing the whole system, conceptually how it is designed and all fits together as a whole, how it's intended to be used, and bring it together in a logical sequence.
Also, look at effective use of figures and tables. With a few good drawings, even very simple diagrams, you can use them to frame what you'll cover in the text. Likewise with tables, don't write out longhand what can be summarised in tabular form.
Just like doing presentations, effective writing comes with practice. And help with review and proofreading will help greatly to spot and improve weak areas. I was lucky to work with a technical writer in my previous job, and she greatly improved the writing technique of many of the software developers on our team. It's a shame that it's not highly prized in software development, because it's an essential tool for effective communication of ideas, and it's a big part of what we should be delivering to our end users and other developers.
Re: Ask HN: How to level up your technical writing?
#140Tech writer here. The absolute, invariable first rule in tech writing is to know your audience. Understand not just their technical problems but take the time to empathize with why they have these problems in the first place. Tech writing isn't about documenting, it's about finding the best way to explain something to people so they can solve their problems. Oh, and use an editor (the human kind, not the digital kind…
> Oh, and use an editor (the human kind, not the digital kind.) This is so important (IMNSHO). It's fairly obvious, that editors are becoming a "lost art." My mother was a scientific editor, and she was brutal (she edited some of my work). It's really hard to find fiction books, that are less than 500 pages. I read a story about Stephen King. Apparently, he hates being edited (most writers don't like it). When he was…