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.
Don’t:
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:
- Don’t strip out the comments from code and put it in a separate file and call it documentation.
- Don’t tell people to just read the code. That presupposes knowing the components of a project and how they interact.
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
nielsonm
bit.ly/badcamp-write-the-docs
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.