We should consider documentation and program code as assets, not transactions.
Here is a piece of code I wrote last week. It is a real piece of code, not a contrived example. What does it mean?
/\(|\)|[^\(\)]*/gJust in case you do not know, this is a regular expression, a pattern-matching instruction which can be used to search text. It means "find all the start brackets, find all the end brackets, and find all the sequences with no brackets in them".
Clever and succinct though it is, I am not proud of this code. Writing it was an act of desperation, as there is no other simple way in JavaScript to search text.
What I do not like about overly-concise code such as regular expressions is that it is almost impossible to read. You have to understand the syntax deeply and execute the code in your head to grasp what is going on. It is a maintenance nightmare.
More generally, code like this undervalues what we deliver. Program code is an asset that delivers value to the organisation. The asset needs to be maintained through time. The net value of the asset is higher if maintenance is less expensive and less risky. The primary requirement of code is to communicate how a program works to a support programmer.
The alternative is to see program code as a transaction, a one-off activity to create a new capability, where concise constructs are a valuable shorthand. Given the choice between a concise syntax that saves the original programmer a few keystrokes, and a verbose syntax that makes the program easier to read, I would always choose the verbose syntax.
This tendency to treat what we produce as transactions crops up throughout IT projects. We treat specifications as one-off instructions for the programmer, not a permanent, definitive description of the program. We treat analysis, design and tests as hurdles that we have to jump, rather than having a lasting worth that goes beyond the project.
Part of the problem is semantic. Project management calls everything "deliverables", but makes no distinction between asset deliverables that have value when the project is complete and transaction deliverables that are only there to support the project. Most project management deliverables, like project plans, are only transactions. Many of the minor and inevitably rushed deliverables, like test plans, are (or should be) assets. The smallest, least significant computer program that you deliver has more lasting value than all of your project plans, schedules, project reports and issue logs put together.
I suggest: