Write the Docs: Always complete, never finished – Daniele Procida

This talk at Write the Docs Portland was given by Daniele Procida. Daniele works at Divio but is soon leaving for a new challenge. This talk was about how you should view your documentation as always complete but never finished, and he has likened the documentation process to the analogy of a growing plant. 

He has a documentation framework that he is well-known for (and which we love here at KnowledgeOwl):

The inspiration for his talk's title came from his grandparents’ bookcase with the maker’s logo that reads: always complete but never finished.

We suggest you go watch Daniele's full presentation to get the full effect--it's amazing, and we're only scraping the surface here. But, to summarize (and we hope we do Daniele justice!):

• All documentation work involves a certain amount of pain, as any difficult thing does. But there are ways that we, as documentarians, create more pain (and more work) than is required by the work.
• The easy part of work is doing it.
• The hard part is knowing what to do.

It is that second pain which Daniele focused his talk on, since this can be the pain that we inadvertently create ourselves. Enter: the complex project plan.

Working on complex projects

As Daniele points out, projects demand plans, but complex projects lure us into creating complicated plans. Until we have finished executing our plans, we won’t have anything useful to show for our efforts. 

Here, he brings in an analogy: if you’re building a ship, it’s not finished enough until it floats. It takes up space in the shipyard costing money to be there. 

But unlike ships, documentation is ever-evolving, because it's usually about a product which is itself being changed, updated, and improved.

Daniele's point is that we fall into a trap when we confuse the finished with the complete. As a living project, documentation will never be finished and never needs to be finished. But it can--and should--be complete.

An analogy of plants

Daniele asked us to think about an analogy of plants and how they grow:

A plant grows through an organic process when it grows, guided by rules that apply to cells without the need to refer to a master plan. In its development from a seed to its mature form, it’s an organism that’s always complete, and always ready to progress to the next step of growth. It’s never finished because there’s always another step in its development. 

The plant doesn't follow a plan or blueprint; it builds itself from the inside-out one cell at a time. It experiences growth when each cell develops according to the rules for that kind of cell. 

Daniele then applied this analogy to documentation (insert sound of our minds being blown): we can apply the idea of well-formed growth that operates at a cellular level, and also the distinction between the complete and finished. Documentation can go through healthy growth that doesn’t need the final shape to be fixed and stable. 

Start small with your documentation

In order to achieve this, Daniele advises several approaches:

• Don't tackle grand plans with your documentation.
• Instead, just look at a tiny unit--such as a paragraph--to iterate on.

This allows you to iteratively improve the documentation and leave it in a "complete" state--without ever getting caught in the trap of thinking it needs to be "finished".

Modelling a camera in Python

Daniele then walked us through an example of this approach using documentation he created for a project he undertook to model a camera in Python.

Rather than laying out headings that would have to be populated, he created headings and content organically as he updated the project itself.

This had several huge benefits:

• At no time was he publishing something lacking – it felt like growing a little bean seed into a plant.
• He published the documentation early and often.
• It never felt like anything was missing from it (so it was complete at every stage).

Final remarks

Daniele closed by advising us all:

Don’t try to solve big problems – just pick up the nearest small thing that comes to hand and work on improving it. You will have the pleasure of watching something grow. 

We loved this distinction ("complete" vs. "finished"), as it aligns with a lot of concepts around Just In Time documentation and agile development which we use, and which underlie a lot the maintenance on our support KB. We'd strongly encourage you to go check out his talk if any of these ideas resonate for you!

Watch the full talk here.