June 1, 2015

Does Documentation Still Matter?

It’s a great time to be a healthcare software developer. You’ve finally broken free from the traditional software development process. You can now use iterative or Agile development approaches to deliver high-quality software in a fraction of the time.

And the best part of it is that you no longer have to deliver all that painstaking documentation with your applications, right?
Wrong. Dead wrong.


Too many Health IT solution providers are falling into the trap of thinking that streamlined development and faster processes have somehow eliminated the need for good documentation. They figure, “Since everything is moving so fast now, surely the top priority is to start cranking out code as soon as possible.”

But the truth is that a well-designed healthcare software application always begins with sufficient and needed documentation. The corollary is also true: if a finished application lacks relevant and comprehensive documentation, it’s probably not well designed and it certainly will be close to impossible to maintain and evolve, plus, it surely will fail any regulatory or another legal scrutiny.

Yes, You Should Still Begin with Documentation

Why should software developers continue to care about documenting their projects? Regardless of what software delivery method you’ve chosen, there’s going to be a great deal of input that defines the type and quality of the solution you’re delivering. And one of the keys to delivering the expected solution on time and within budget is the availability of accurate, up-to-date, easily consumable documentation.

In other words, no matter how much the software development cycle has changed, it remains true that documentation isn’t just a task to be done hurriedly when the project is about to be finished. Documentation is a vital activity that helps track decisions, provide context for the solution and allows internal teams and partners to further develop the solution over time.

What to Document and Why

Am I advocating a return to the days of waterfall development where every project began with endless project planning meetings that culminated in a 420-page requirements document? Well, no.

But I am saying that no matter how Agile you plan to be, there should be a single place of reference that team members can go to gain an understanding of factors such as:


  • All major design decisions
  • Data-related and technical assumptions
  • External system dependencies and integration assumptions and constraints
  • Environment configuration
  • The technology stack used with the specified versions of the major software components
  • System architecture with the list and diagrams of the system components, their high-level functionality, purpose, and responsibilities
  • Detailed feature specifications with the specified flow of system interactions, alternative flows, pre and post conditions, as well as business rules
  • Traceability matrix tracing business requirements to their design, implementation, testing, and completion
  • Non-functional requirements (including performance, security and monitoring/auditing) and how those are addressed within the design and implementation

The more complex your development environment, the greater the need for agreement—and hence, detailed documentation—on all of these points and more.


What Good Documentation Can Do for You

Rather than being a burden, good documentation that’s created at the beginning, during and upon completion of a project actually becomes a wonderful resource. It gives everyone on the team a centralized place where they can refer to decisions that have been made and expectations that have been set. And if your team, like Vicert, eschews email and embraces a social communication tool instead, you’ll make life that much easier for everyone.

Ideally, then, your project documentation won’t be a write-it-once-and-forget-about-it kind of thing. It will be an evolving set of documents to which you add learnings that were gathered and decisions that were made throughout the development process.

Each addition to the documentation will not only help guide your team through all phases of development, but also serve as a valuable resource for launching your next related project efficiently.

And that’s not the end of it. When your star developer leaves your organization or you change vendors, your documentation will be an essential knowledge transfer tool for whoever picks up the maintenance of your software.

So, yes, you still need thorough documentation, but like the software you are building, plan to continually update your documentation rather than taking a big-bang approach at the end of the project.

If you found this article interesting, sign up for more. At Vicert, we believe in the value of sharing knowledge in articles like this.

Author: Dejan Nedic
Like this article? Share it!