Documentation Is Code

Code is a design, written in ASCII (usually), that is readable by an interpreter or a compiler. It tells the interpreter or compiler what to do.

Some documentation is a design, written in English, that is readable by a human, and tells said human what to do. Look in a cookbook. This is a library of instructions (programs), and they instruct the runtime interpreter (your brain) on how to make one or another meal.

When building software, the user must always be considered. One way to do this is to take the stance that the user is an integral part of the system you are building, and assume that DocumentationIsCode. When you make this assumption, you make the software developers responsible for writing rough drafts of user doc for every use case. The feature isn't done until you have the software running on the hardware (the code works) and you have the treeware working on the wetware (the doc makes sense). Often, you will want a TechnicalWriter to clean everything up and make a proper manual out of all the use case user doc, but let the developers "program" the users by writing the instructions in the first place.

But why? What is the value resulting from creating documentation that goes unread?

1. It focuses developer attention on the user and how this feature will support what they want to do.
2. It gives them an incentive to write the program in an intuitive (from the users' POV) way. The more self-evident they can make a feature, the less time they have to spend writing user doc. Since most programmers hate writing documentation, this can be a powerful motivation for implementing a good UI in the first place.

How so? What is going to change to cause the developer to focus any more attention on the user when writing in a word processor over a code editor? How does writing the document cause the developer to make a good UI any more than creating it in the code editor?

---

The very correct expression, DocumentationIsCode, leads me to another: DocumentationCannotCompileRunOrDoUsefulWork.

---

CategoryDocumentation, LineByLineReview