I’m at Write the Docs today in Portland and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Nina wrapped up the presentations before lunch. When she started college every Freshman had to take a writing course. The papers weren’t graded but her first paper did very well. As she sat down to write the next paper she thought, “This one will be even better.” She got to an empty page. Thankfully she got an extension; which got her thinking about how to make writing easier on herself.
When you’re under pressure the worst place to be is at the beginning. With nothing written you have no momentum.
Nina now works at a software company making development tools for mobile developers. Their customers create new projects that are already filled with template code that compiles and runs. They don’t start with a blank page. How can that programming approach be applied to writing?
The first thing we should absolutely be stealing is starting templates. Don’t start with a blank page. Make a ‘Hello World’ document. Make a template for every single type of document that you publish often. It’s not about the content; you’re just interested in setting the foundation for the layout, structure, and guide for published content you like.
To solve miscommunications around docs Nina recommends making a spec. For documentarians the doc is the product. The spec helps you get there. Use it to define the questions you’re answering for your readers and for yourself. What kinds of questions can we ask? Things that help us understand who the target audience is, the current state of the documentation on that topic, and who will be doing the work. This will change not just what you write but how you write.
A lot of us start with outlines when writing. It lays the foundation, or so we think. The problem is that the outline at the start of writing a doc is never the outline at the end of writing a doc. The programming lesson Nina recommends here is design patterns. This is essentially a prescription for solving particular patterns and problems in code. The solution is customized and implemented to solve the problem in a particular context. You can do this by starting with architecture rather than an outline. Know what type of document you’re writing and then start the process.
If you can't figure out what to call something, calling it twelve different things is the worst thing you can do @misskallisto #writethedocs
— Elizabeth Urello, eurello.bsky.social (@eurello) May 5, 2014
When writing docs we strive for clarity. But we often fail. On way this manifests is using multiple terms to refer to the same thing; consistency matters. A cornerstone of good programming is naming your variables. Nina argues that this is a cornerstone of good writing, too. Be consistent, be specific, and be deliberate in your naming and your writing.
Editing is another key component of good writing. At Nina’s job they do peer editing. To help clarify that concept Nina turned to the concept of code refactoring, or restructuring existing code without changing its external behavior. For your docs, don’t just edit, refactor.