The Write The Docs Conference was started in 2013 as a simple idea. Bring together those that write professionally in technical fields, creating documentation, educational papers, scientific research or other ideas of this nature. Several people got together to organize this, thinking that even a moderate turn out of writers would be considered a success.
However a moderate turnout of 50 or 60 it wasn’t, it was a huge turnout of hundreds of people. Maybe I should say documentarians? Energy was high and individuals were ecstatic to meet others working on this oft overlooked area of technical work. It was such a great turnout and solid, useful and valuable energy among everyone that the organizers pushed forward and decided to have two conferences this year. One in Europe in the grand city of Budapest. The Write the Docs Conference will be back in its birth place of Portland, Oregon.
With the Budapest over I’m looking forward to getting a review of the event from Troy Howard @thoward37 and experiencing this years conference in person. If you’re looking to go, be sure to get tickets soon, they’ll very likely sell out of space.
Thoughts and Questions
This however brings me to the culminating point of this blog entry, that was ignited at the conference and inspired me to do more than just dwell alone in pondering what, when, how and where to write documentation. I started wondering and talking to people regularly about things related to documentation.
When should I start writing documentation?
Sometimes, it’s a good idea to start writing documentation before any coding actually starts. It’s a great idea to start documenting the ideas, thoughts around workflow and related matters pretty early. It helps to write down thoughts because it helps to confirm understanding and ensure more concise communication. At least, that’s what I have found. I wouldn’t be surprised if others experience this too if they give it a try in the earlier stages of a project.
How should I write documentation?
This is an interesting matter. Is it in story form? Such as in the form of a user story or that of a fictional story of someone using the application that would prospectively be built. Should just the entities, domains or other elements be written about? What should be written about these things at such an early stage? Isn’t this all part of BDUF (Big Design Up Front, and horrible anti-pattern)?
Watching out for BDUF is critical to success. Avoid it with energy and gusto. However confirming the entities and domains of a project, writing them down so others can more decisively understand what they are is important and useful. Writing stories of the application, also can be extraordinarily useful!
Many other questions come up and I’d love to see material on practices and ideas others have had. This is one of the big reasons while I’ll be attending Write the Docs. I hope to see you there, maybe we’ll get some answers and ideas wrapped up into some documentarian solutions!
For some great photos of the Budapest event…
Fellow Documentarians: There are many good memories of @writethedocs EU 2014 stored in this photo set. http://t.co/cE9n0fZaZ8
— Write the Docs (@writethedocs) April 4, 2014
After our own horrible BDUF experience, we invested in smaller docos and came up with this Use Case template for application development. https://gist.github.com/cliveb/10016881
As far process documentation, we found developer blogs are best, I think they work better in public, because of peer reviews (only a few dev docs, security/ encryption/licence need to be internal docs).
On product doco and help. Via our logs we noticed customers progressively stopped reading documentation, except for a very narrow set of folks either genuinely trying to figure out our configurable business logic, or looking to justify a feature request as a software bug (hence the importance of our Use Case template).
A nice intuitive interface design with simple icons on eye helps avoid help doco and T9N altogether. I’d have to say a video works better than almost any help system for configuration logic. Illustrations, cartoons, stories from cool designers (this is why doco should report to snr dev and not marketing, alas I digress).