- Date/Time
-
Nov 18, 2015 @ 16:00
- Abstract
-
http://cfp.devoxx.ma/2015/talk/TSV-1813/Writers_Write!_The_Documentation_BOF
- Moderators
-
Dan Allen, Guillaume Scheibel
- Add comments
Dan Allen kicked off the session by sharing advice he gave someone who wanted to be a writer. He said that time is an important but often ignored factor. It’s a negotiation with your brain. Take a few minutes to write an abstract and bullet points about what you want to share. Your brain will then kick off a background task and start working on it. Over the next few days, fill in more and more ideas until you are ready to start putting together a story. Also have a queue of ideas so you’re always working on something, fills in the pipeline.
The group then discussed / debated:
-
should documentation be done by a single person (i.e., a single writer)?
-
which docs should developers be responsible for writing (API vs end user guide)?
-
where the docs should live?
-
should the documentation team be separate from the development team?
-
what is the role of the documentation team?
A question came up as to how much technical detail should be in the documentation and how you know when you’re done writing. Dan suggested user interviews as a way to know if documentation is complete enough. Markus Schlichting suggested that the documentation should be organized in layers, with each layer revealing greater depth that the user can navigate to through xrefs on an as needed basis.
There was general agreement that if the documentation is in a separate system, developers won’t do it. Period. The content should also be in plain text or developers will hate it.
The group discussed how documentation should be part of code change or the code should fail the code review without docs. It’s a culture change. Developers can be tough on each other by outright rejecting code if documentation is absent just like they would reject code if tests were absent.
On the other hand, this can be a problem because the new content may not fit cleanly into the whole. If it’s too narrowly focused, you get tunnel vision. The documentation is right, but doesn’t fit nicely or sensibly into the whole. So having documentation isn’t enough. You need an editorial manager to guide it and make it fit. There was some debate about when this should happen. In general, the group seemed to agree that getting any documentation was certainly better than getting none, going back to that cultural change.
This was one of the most successful BOF sessions I’ve ever attended. Everyone in the group contributed at least once. I credit that the roundtable arrangement and the emphasis on getting everyone to participate.