4 reasons to invest in knowledge sharing and documentation

We want to give a shout out to the documentarians, the developers who invest in documenting for their team, for clients, and for their future selves. But nobody went into coding because they liked writing documentation.

Additionally, few companies really measure developer output by how much documentation they produce. Even in companies with strong formal policies on documentation, delivering new features is the top priority. Today, developers have to care about much more than lines of code; they care about the whole business.

As tedious as it may be, though, knowledge sharing and documentation should be a basic part of the software development cycle. How? Start daily and incrementally, and find the right tools that ensure the code is kept maintained and that the documentation is closely coupled with the code. Doing so takes time, but it’s worth it.

Why is it so important to have strong knowledge sharing and documentation of code? Here are four key reasons.

SEE ALSO: Certificate lifespans are getting shorter and it’s never been a better time to automate

Discoverability – don’t reinvent the wheel

Often, it seems, the best solution to a software problem is the solution that already exists but is introduced with a new technology. Inside software organisations, it can be difficult to know what’s already implemented, leading to duplication and wasted time and effort. Worse, the company can end up with several different implementations of the same feature, each relying on different frameworks or libraries and needing its own maintenance, creating needless technical debt.

If another team has already implemented a feature or some useful infrastructure, other teams should know about these components and use them (where appropriate) instead of building them from scratch. In order to know what’s out there, there needs to be some high-level documentation of features, like a catalog or searchable database.

Remote communication between developers

If you don’t understand some code, you can always ask the team who maintains it, right?

That’s nice in theory, but in reality, it’s often not so simple. That’s especially true in international or remote teams, and when a service goes down, time differences can be critical. Differences in culture, time zones and language can all be easily fixed with proper documentation and knowledge sharing. When a team deploys a healthy documentation culture, developers can find the information they need when they need it.

Debugging

Debugging is really two different processes: first, finding the cause of a bug and then, fixing it. Often it’s finding the source of a bug that takes the most time.

Both finding and resolving bugs in code you wrote can be complicated by itself. With no documentation, debugging someone else’s code can become very time-consuming and confusing. There are two main challenges in this case – first, understanding the big picture of the entire flow. While bugs usually lie down in the details, it’s crucial to understand the bigger picture in order to make sure that the possible fix makes sense. Second, it’s nearly impossible to understand, just by reading code, why the original author has created it the way he or she has. The author could have chosen many other paths – but while creating this code, they made some meaningful decisions, which are important to understand when figuring out where a bug may be lurking, and also what’s important to keep in mind while fixing it.

Even if you wrote the code yourself some months ago, it can be hard to remember exactly what it does. Document for the next guy, but remember that the next guy could be you!

SEE ALSO: “Cloud moved decision-making responsibility out of finance and into engineering”

Onboarding

Starting a software job can be daunting, diving into a new codebase especially when being told “One day, all of this will be yours… and that day is today. Good luck!”

Different development styles, unusual techniques or even code that seems deceptively familiar at first glance; all of these are challenges that a new developer faces. Proper codebase documentation helps new employees understand that code faster, making them valuable assets to a team, reducing training time and ramp up (for companies that are lucky enough to have a good training process beyond throwing developers in at the deep end).

As you can see, a culture of documentation and sharing knowledge brings benefits across a software company. When new team members see the value of good documentation, they can become champions by paying it forward, documenting their code as they write it and ensuring that debugging, onboarding and documentation become easy. Great code is documented code.

The post 4 reasons to invest in knowledge sharing and documentation appeared first on JAXenter.