Heinrich Hartmann’s Writing Advice


Heinrich Hermann has great writing advice for developers (or engineers). The His suggestions are true to all the aspiring writers. The article is full of goodies which would be very helpful for aspiring writers.

  1. Personally I never had an intrinsic interest in literature, so writing did not naturally come to me either. I have spent days and weeks agonizing and procrastinating around larger writing tasks. And to this day, having pressure to produce high-quality documents on a deadline gives me nightmares.
  2. If you don’t have a clear message in your head, your are not ready to start writing a narrative yet. You have other things to do first: Research the topic and find your message. It’s important to realize that these are different tasks. They may involve writing in the form of note-taking or journaling, but this is not material you would directly use in the final document.
  3. Writing is generally a great way to learn, but one has to realize that you are doing it. Learning is a slow process and requires patience. It is not helped much by agonizing in front of a screen, trying to squeeze out another sentence. Doing more research on the topic by reading a book, blog or paper and taking notes may be a better time investment.
– Heinrich Hartmann

Hartmann’s next experience is much the same as mine. I, too, spend days and weeks agonizing and dithering around the writing task and even thinking about it in the midst of the nights.

  1. Writing requires intense focus over long periods of time. Ideally you want to get into a flow state where you are zoned in and working on the text for hours on-end. This is by far the most efficient way to write a narrative or a blog-post – at least for me.
  2. Prepare for a writing task, like you would for a hike. You are in for a grind. Find a comfortable space to sit. Grab a beverage/snack of your preference. Most importantly make sure that you are rested and able to focus. Don’t start a writing task when you are already tired. There is no way you will get anything useful written.

In my case, I do make most of the writing blueprints during my day-to-day walk. As an early bird, my effective writing practice takes place early in the morning.

  1. For documents that are more than a page long you must take a top-down approach and start with an outline. An outline is a list of sections together with rough notes, often in the form of bullet points. For this document the first outline looked something like this.
  2. When writing, you want to arrive at a good story-line for you document, before you start fleshing out and polishing the text. A outline should be the first milestone for any larger document you are writing. The outline, should convey the main message and provide a clear “red thread” that guides your reader through your argument.
  3. Remember: The first milestone for your document is an outline. Everything that is not directly contributing to this goal is a distraction.
  4. When you are happy with the outline, the second milestone is a fully fleshed out text, where all notes have been converted to paragraphs. The text should cover the intended content but does not need to be polished or well written.
  5. Once you are at this point, you start worrying about polish: Remove typos, improve wording, restructure paragraphs. Also work on figures and publishing can be delayed to this point without any problems.

The next advise from Hartmann is just to keep writing.

  1. Keep writing. The only way to improve your writing is by writing. As with practice in general, valuing quantity over quality is generally a good idea. Developing a writing muscle, and writing relatively short medium quality documents every week will make you a much better writer than crafting highly polished documents once a year.
  2. Leverage small writing tasks as exercise. Most of the rules that apply to writing long-form documents like Tech Narratives, Blog Posts or Papers hold up for writing short documents like E-Mails or issue tickets. Use this documents to practice your writing skills, by make them well structured, usable and polished.
  3. Get early feedback on your outline. Once you have constructed an outline and polished the story-line you are at a great place to get initial feedback on your document. This allows you to uncover flaws in your story-line early, and make sure you are on-target with the content. Also, reading an outline is a very quick thing to do, so it will not take a lot of effort for your reviewer to go through your text.

After completing the first draft, then work on removing the most egregious grammatical and spelling errors.

Related Resource