I’m probably generalizing, but I’m going to say it anyways … I think most developers hate dealing with documentation.
Whether it’s documenting the source code written during software application development, or end user documentation for the actual customers who will end up using your software, most developers I know really dislike having to deal with being responsible for it.
It certainly seems to get short shrift during project scheduling as well. In traditional waterfall methodology, developing documentation for code and for the end users certainly got planned during the scheduling and planning of a project.
But in reality, when deadlines get missed, and the development team realizes they’re going to miss crucial milestones and project deadlines, you can guess what happens next … the project manager looks at the tasks and milestones in the project plan, and figures out what can be jettisoned from the project without affecting the overall deliverables too severely.
Nine times out of ten, the documentation always seems to be the first thing to go. Project managers and developers alike, seem to be of the same opinion that documenting the implementation of a software application is much less important than getting the software out the door and into customer’s hands.
The newer Agile/Scrum methodology, doesn’t seem to place much importance on documentation either.
Thinking about documenting what you do during software development often takes significant time and effort, no question.
But the very nature and philosophy behind agile driven development kind of says it all .. AGILE = SPEED = WRITE YOUR CODE AS FAST AS POSSIBLE
Nothing in there mentions dealing with the other parts of software development, such as being sure you document what you’re doing during the application development cycle, does it?
Agile and scrum methodology even has a phrase that I hear get bandied about by product owners … “analysis paralysis”.
What analysis paralysis implies, according to agile/scrum advocates, is that thinking about documentation and up front analysis of software project requirements only slows software development down.
So if waterfall and agile/scrum methodology place little to no importance to documentation, it must mean that it’s really not crucial to the success of a software project, correct?
WRONG. WRONG. WRONG.
I recently inherited a software project from a coworker who recently left the company. The coworker who left, inherited that same project from a previous developer who also left the company. Keep repeating that cycle for another two or three developers who either no longer work at the company or work in different parts of the company and are no longer responsible for maintaining the application.
Each developer who inherited the project never bothered to create any documentation about how the application was architected. Or the overall technical stack and programming languages were used. The database and web servers.
Maybe one or two documents scattered here and there. But nothing centralized in one easy to find place.
Can anyone say “technical debt”?
Imagine you’re me, inheriting an application that has grown over time, never once properly documented, and you’re suddenly the “go to programmer” for any problems or requests to enhance the application.
Some software developers that I know will boast that reading the source code is the ultimate documentation. By understanding the source code, they say, you will gain all the insight you need to completely understand the ins and outs of an application.
There are several big flaws with this line of reasoning.
First, we’re assuming the source code is in a good and legible state, written by programmers who know what they were doing.
But what if it that’s not the case? What if the code is flawed? Full of bugs? And written poorly and only barely understood by the original programmer?
The second flaw is making the assumption source code explains the original INTENT of what the code is trying to accomplish from a business objective standpoint.
But software development, unfortunately, does not work that way.
You start with the non technical, business requirements of a particular want or need, and THEN translate those requirements into source code a computer can understand.
It’s very, very difficult to start in the other direction and try to glean what the business requirements are, just by reading and analyzing source code.
Think about how lines of source code an operating system like Microsoft Windows contains.
Somewhere in the ball park of 50,000,000 lines of source code.
FIFTY MILLION LINES of code.
Does anyone who believes in the notion that reading source code will help you understand what a software application does, really willing to invest the time and effort into reading 50 million lines of code?
That’s the problem with source code. Source code is language that computers can understand.
But source code, even to experienced and seasoned software developers, can be difficult to comprehend, because a human must mentally translate computer code back into human level concepts.
Human languages are something we humans EASILY understand.
If I read a well written and legible document written in a non technical style, that clearly explains the high level intent of a software application, it helps me to get a nice 30,000 foot level overview of what the application is trying to accomplish from a business oriented standpoint.
Better yet, if I use a modern wiki based documentation system, I can use the power of hyperlinking different documents together, using image and video files, and many other helpful electronic tools to create a nice centralized documentation system that can be accessed from any accessible networked computer device.
I’m already busy creating a new developer wiki portal for that software application I inherited from the previous developer, but wondering if my introduction is appropriate or not.
“Call me Ishamel … ”
Too literary?
