technical blogging: lessons learned getting started

gistfile1.md

technical blogging

lessons learned getting started

develop a formula

• meta/method vs content:
  • When I read articles, I don't just want results. I want to learn how to do things myself--reusable stuff.
  • Try to orient small things in context of bigger things.
    • Even if this isn't done explicitly, point of view & meta stuff can still be picked up by your readers.
  • THinking in terms of a bigger picture helps to find gaps in discussion or explanation of specific examples

figure out how you work best

• so...try different things.
  • turns out I'm far more efficient writing on paper than on a computer.
• don't overdo it.
  • just like with coding, I found taking a break so helpful to get fresh perspective.

have a point & get to it right away (above the fold).

• simon peyton jones article on a good research paper: mostly applies
• you have to know what your point is. and have to tell your audience about it. assuming they're in passive consumption mode, or scanning to try to solve a related problem. hence:

help them scan the page.

• whatever the source of their distractedness, readers need help scanning the page.
• break up blocks of text with headings, code snippets, screenshots, pull quotes, other visuals.
• repeat yourself liberally to keep the scanning reader focused on the overall flow.
• jakob nielsen has been saying this for YEARS now. see alertbox for more.