The Ruby on Rails and ClojureScript experts

Sep 11, 2017

Here is a collection of articles that I found helpful when it comes to technical writing:

What to write

Jacob Kaplan-Moss writes about three kinds of technical writing:

Tech docs can take a bunch of different forms ranging from high-level overviews, to step-by-step walkthroughs, to auto-generated API documentation. Unfortunately, no single format works for all users; there’s huge differences in the way that people learn, so a well-documented project needs to provide many different forms of documentation.

At a high level, you can break down the different types of documentation you need to provide into three different formats:

  • step-by-step tutorials,
  • overviews and topical guides to the various conceptual areas of your project, and
  • low-level, deep-dive reference material.

Technical style

Jacob Kaplan-Moss writes about how to develop a writing style that produces great technical documentation.

You need an editor

After writing about what and how, Jacob Kaplan-Moss writes about the need to edit your writing. Ideally it’s someone else, however he also has tips for self-editing.

Two nuggets:

  • Give it time - put some time between the tasks of writing and editing.
  • Shake things up - in order to get out of a rut, change the page margins so that the text flows differently and doesn’t look as familiar.

How to ask questions the smart way

Eric S. Raymond and Rick Moen’s gold standard for asking technical questions:

In the world of hackers, the kind of answers you get to your technical questions depends as much on the way you ask the questions as on the difficulty of developing the answer. This guide will teach you how to ask questions in a way more likely to get you a satisfactory answer.


  • Introduction
  • Before You Ask
  • When You Ask
    • Choose your forum carefully
    • Stack Overflow
    • Web and IRC forums
    • As a second step, use project mailing lists
    • Use meaningful, specific subject headers
    • Make it easy to reply
    • Write in clear, grammatical, correctly-spelled language
    • Send questions in accessible, standard formats
    • Be precise and informative about your problem
    • Volume is not precision
    • Don’t rush to claim that you have found a bug
    • Grovelling is not a substitute for doing your homework
    • Describe the problem’s symptoms, not your guesses
    • Describe your problem’s symptoms in chronological order
    • Describe the goal, not the step
    • Don’t ask people to reply by private e-mail
    • Be explicit about your question
    • When asking about code
    • Don’t post homework questions
    • Prune pointless queries
    • Don’t flag your question as “Urgent”, even if it is for you
    • Courtesy never hurts, and sometimes helps
    • Follow up with a brief note on the solution
  • How To Interpret Answers
    • RTFM and STFW: How To Tell You’ve Seriously Screwed Up
    • If you don’t understand…
    • Dealing with rudeness
  • On Not Reacting Like A Loser
  • Questions Not To Ask
  • Good and Bad Questions
  • If You Can’t Get An Answer
  • How To Answer Questions in a Helpful Way