Skip to content

Instantly share code, notes, and snippets.

@mojavelinux
Last active November 8, 2016 17:28
Show Gist options
  • Save mojavelinux/e12d9a535ceaaa47f24a to your computer and use it in GitHub Desktop.
Save mojavelinux/e12d9a535ceaaa47f24a to your computer and use it in GitHub Desktop.
Notes from Writers Write! The Documentation BOF at Devoxx 2015 (MA & BE)

Writers Write! The Documentation BOF: Notes

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

https://gist.github.com/e12d9a535ceaaa47f24a

22952480900 84c5545fee z d

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.

Video clip of BOF in action!

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.

Additional notes from Devoxx Belgium

  • not sure what to write

  • start by writing without worrying about editing; just get the information down

Asciidoctor wishlist

  • publish chapter by chapter using Asciidoctor

  • a quick preview for AsciiDoc-based Javadoc in IDE

  • IDE navigation of includes within AsciiDoc-based Javadoc

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment