Modern development projects always come with documentation requirements, and many project teams struggle to provide this documentation. This documentation is for all types of information: stakeholder and user interviews, design decisions and wireframes, business workflows and rules, system maps and internal API documentation, developer workflows and processes, documented code and tests, and, ultimately, hand-off documentation to clients. At any point of the project, from beginning to deployment to client acceptance, any of this documentation may be vital for making decisions about the project.

Generally, as an industry, documentation is seen as a barrier to progress, as something that can be put off until later. This is obviously a trap, one that developers can easily fall into with every project in which they participate.

To avoid this trap, a simple acronym can be leveraged to help keep documentation efforts focused on a daily basis: ABO. Always Be On-boarding. Project team members should continuously create the type and level of documentation that any team member — stakeholders, product owners, designers, and/or developers — can use to quickly get up to speed with the project. This effort will, obviously, provide a better and faster on-boarding experience, a easier, less stressful method for creating end-of-project or hand-off documentation, and provide stakeholders with more confidence in the current and future state of the project.

In this article, we take a step back from our project documentation problem and find some rational and practical reasons for creating a less rigid pattern of continuous documentation and how healthy this pattern is for your projects, your teams, and your clients.

Why On-boarding Matters

Continuous Documentation is an interesting idea. As an Agile "core practice", it has drawbacks that clearly make it very easy to quickly dismiss when it comes to time and budget. While the idea is to "have potentially shippable software every sprint", in many ways this may be impossible.

And, while in a perfect world, continuous documentation might be nice, practicality is called for with documentation. This is where the idea of Always Be On-boarding comes into play.

The idea being advocated here is to create and update documentation as the project progresses while the reasons for the decisions made are clear in the minds of the development team. We aren't talking about a 20-page book report detailing the history of application security. Simply placing a "Security" section in your repository's README.md file and adding a paragraph about how your team handles login security could be helpful to everyone on the team, especially developers added to the project in the future.

Let's dig into the on-boarding of new team members.

Ramping Up New Team Members

A definition of on-boarding for our purposes is the activity any new developer or designer goes through to get up to speed with a project. If there is great on-boarding documentation — business rules, set up instructions, code documentation — that can take a typical developer a couple of days to get up to speed by themselves. If there is no documentation, it can take the entire team many hours to get a new developer into a position to contribute to the project.

What happens when another developer joins? Then another. The math is painful. And on-boarding can be very frustrating to every team member. New team members are frustrated because they do not have information, and current team members lose patience when (repeatedly) answering questions.

In this scenario, delaying the creation of project documentation until just before the project is delivered puts more strain on the project team than simply creating the documentation as you go.

We have great places to document our projects for on-boarding. Markdown files can be stored in the repository for all technical documentation. You can document anything required to get up-and-running with your projects, from any global software install to how to deploy the application. While using a wiki to compose this documentation may be an option, having the documentation available with the code should be considered helpful. A wiki page, or pages, may be deleted after a project is completed, but documentation in a code repository is forever (hopefully).

Please Note: Never put important and secret information into your repositories. I know it is stupid to have to make a "Please Note" about that, but here we are.

Avoiding Documentation Technical Debt

The worst-case scenario with documentation is delivering documentation at the end of a project. As in, a decision was made at some point early in a project that documentation should not be dealt with until it was actually required by the client. If this is how your projects work, then you understand the pain of spending a great deal of time under stress trying to generate documentation in hopes that it may get you off the hook.

This is technical debt, similar to the same debt that occurs when testing is treated as something that can be put off until later.

What is being proposed here is to spend a small amount time with each pull request to make sure that documentation associated with the code being created and updated is also updated. Did you add a new Node library to the project to add functionality? Document that functionality and how that library provided it. A simple sentence or two of explanation with a link to the library's Github site could give more insight into the decisions made.

When you do this, months from now you will avoid the "Why are we using this library?" conversation with the client team during hand-off. Do you think "Uh, I don't remember" will ever be a good answer?

While the kind of ABO documentation suggested here would not be exhaustive, it can provide the framework for which the final documentation should take. Writing a paragraph about the business rules for a feature today can make updating that information tomorrow easier, and make finalizing and delivering hand-off documentation much less stressful. And having that information available with the project helps to provide stakeholder confidence toward future efforts.

Tips On Implementing ABO

As always when implementing additions to your team's current workflows it pays to be practical. There needs to be buy-in from everyone on the team so that everyone knows they have to hold themselves and others accountable.

If you work for an employer that often rotates developers across project teams, convincing you teams to implement an ABO approach should be fairly easy: the more difficult it is for new team members to be on-boarded to your project, the more difficult it will be for team members to be rotated. You may be stuck on the project until it is completed. And nobody can be quickly added to help out.

If you work for an employer that adds team members to projects for heavy development periods, or during extra stressful times, the team should know that a low-stress on-boarding process assists this practice: if there is poor on-boarding documentation, the potential assistance a new team member might provide will be cancelled out by the increased time and stress getting that new team member into a position where they may make contributions to the project.

The logic for implementing ABO is there. Lets take a look at how we can best implement it.

Start Documenting from the Beginning

The best time to begin documenting your project is, as always, at the beginning of the project. Start by making certain there are instructions on how to install the project along with any notes about errors that can pop up along the way. If you are working behind a client's firewall, make sure you add the contact information for the client's help desk in case a new team member needs to be added. This information allows new team members ways to help themselves.

By starting at the beginning, you can set the framework around how the team can contribute to the documentation. It also sets expectations around the continued efforts that will be required.

The Responsibility of New Team Members

When new team members are added to the project, make certain that their first task, getting their environment up for development, has a deliverable: a pull request updating the information they were provided to get started. This PR can update or change the current documentation as well as add any new information that may assist future new developers with their on-boarding.

Does This PR Need Documentation?

When creating a pull request, always ask yourself a simple question: does this PR need documentation? While the answer to that question might reside in the description of that PR, that description gets buried in the repository under all subsequent PRs. Documenting decisions made leading up to the changes in the PR could be very valuable to future developers. Notes on frequently encountered errors will help the team debug problems. Again, anything that lets new developers resolve common problems makes for great documentation.

In Conclusion

Using the Always Be On-boarding pattern should be considered helpful to project team members and stakeholders. Using ABO sets up the eventual deliverable of hand-off documentation reducing end-of-project stress, collects decisions and actions taken as projects progress creating a informational audit trail, and allows for a less stressful and more efficient on-boarding process for new project team members.