Writing prose is not exactly like writing code. However there are similarities since both activities are primarily about editing existing material, but in the composition they are different. When writing prose there is an advantage to freewriting, by simply letting a pen slide across the page from one word to one sentence to one paragraph with little conscious thought. With freewriting the author is growing a tree which can be carved into the story they wish to tell.

I don’t need to write about how badly writing code without deliberate thought generally goes.

What unites both activities is a need for structure. These structures are learned by novices and implemented by journeymen before being developed by experts. In writing software, we have the cocept borrowed from architecture called design patterns, but we can also think of the standard algorithms and data structures we reach for in solving problems as part of the category of learned structures. In prose there are archetypes, rhetorical devices, and dramatic structures. And stories, all texts, tend to have beginnings, middles, and ends. These also have different lengths. (The middle bit of a film is longer proportionallly than the start and the end.) There is also a directed flow of information.

To write better — documentation, blog posts, essays, stories, emails — favour a form which goes from the general to the specific.

Behind the curtain:

I am writing the first draft of this in my phone while sitting on a train. I’m just leaving Beeston station. The form of this essay comes from some style notes I made after reading Warren Ellis’ site morning.computer and many other short form writers. The ideas aren’t unique to me and certainly not applicable in all circumstances. However, I believe that a good grounding in narrative structures and styles helps communicate ideas more effectively, which leads to better documentation that’s easier to write.

The general form I followed above was an attempt at this:

  • A good slogan/title
  • A good image at the bottom of the post
  • Inverted Pyramid form. The general to the specific
  • Three paragraphs. This isn’t a golden rule, but seems to dictate the form of many posts -1st Paragraph – Introduction. General statement. Location & Situation
    • 2nd Paragraph – Limited continuation. – Action & Affect
    • 3rd Paragraph – One or two sentences. Short. The summery
  • Sometimes there is a Reading/Rereading/Listening/Playing style block at the bottom
  • The paragraph rule is often broken with one or two paragraph posts not being uncommon, but always following the general specific direction
  • Quotes are liberally used
  • Word counts for posts examined at www.morning.computer:
    • 192
    • 187
    • 181
    • 202
    • 135
    • 52
    • 235
    • 368
  • Target 200 words