How to do documentation successfully as part of software development

Don’t despair

This isn’t just a software problem

Useful knowledge transfer is a whole field – education

and epistomology

Ida Rhodes, a coder of the univac one machine. Computers didn’t semantecs, translation

Make an argument to convince others to document

Side thoughts:

A key part of documentation is searchability

which goes back to my idea of searching first the places i know, and then the rest of the internet

so being able to search an internal wiki, public documentation, and then below those results (if any) pull in results from DuckDuckGo

Bus plan

everyone uses this- what happens if so and so gets hit by a bus?

Visceral, easy to communicate– and easy to have had specific examples

every use gets less effective (as any appeal to fear, management by crisis)

Poll: Time to first commit on a project? 6, 12, 32, 60?

[i’m not clear on the context… from a developer standpoint, i start a project with a commit]

most big successful tech companies have the goal of getting code on production on the first day

hard to drive direct throughline between investment in documentation and

If a community: It helps a project look bigger, more mature

huge welcome mat

a whole two-week sprint of doing nothing but writing documentation you could probably do all the documentation.

Get the whole team involved: Get food & beverages; have hourly stretch breaks; Get your PM to review PRs. Your manager can write docs too.

Break it up

Add paragraph breaks, a vacation for your eyes.

Gifs, pictures

Licecap - make a .gif Quicktime - audio & video (me, to myself: what year is this?)

Get documentation issues into backlog for sprints. Same thing, review it, ship it.

Create an index - automate that, if you can. If you can’t - make it single page & exhaustive. Encourage others to contribute to it.

Let non-technical folks edit. THey spot super computer science jargon, and they know the why and how

Add documentation as a step in the tasks template.


Skip the README. (No docs, i say later.) Don’t make it wrong - Bad documentation is worse than no documentation. Easy fix: mark out-of-date documentation as such.

Don’t do half-measures.

Don’t do code as docs:

Tim Cosgrove - empathy for idiots - you think he’s talking about having empathy for idiots, by my second time reading through the slide i was the idiot



if you have a wiki, how do you build buy-in and adoption

Slack pinned messages with the wiki

IRC or slack bots with the link in there for you, if you prompt the question

If you get four people working on documentation it starts to take off

Clayton: there has to be an easy way to do this - very Drupal-specific question, documentation for end-users

me: tips for managing the interplay between

He likes tour module. Or Joyride. Look and see how Jacob Rocowitz did inline documentation, with videos.

Jacob: Drupal’s help system does need help to work properly; in webform

in core there’s an initiative, “Help Topics” - a UI for managing all the documentation in core and having a way to tweak it. All stored in YAML files.

Came to Drupal from Symfony; Drupal 8 uses a lot. Symfony has great documentation, amazing documentation. I miss the documentation symfony has– it’s a parallel project, for all four versions of symfony.

me: Interplay between docs and (realizing) there’s a bad user experience, and fixing it. Virtuous cycle to manage relationship between recording (basically workarounds) in docs, and turning that into a task to improve the software, and making sure the documentation is updated afterward - i didn’t say it that well, and he didn’t understand my question.