A Developer’s Knowledge Architecture

Part IV of a four part series on developer efficiency and knowledge sharing. You may read parts I, II and III once you have finished.

One of the epic challenges in enterprises is getting a handle on all the tools that are in use in the organization. Whenever the topic of a new tool comes up in meetings, I usually hear something like this:

“We already have so many knowledge & collaboration systems, why do we need another?”

It’s a common question asked by IT leaders and a fair point. Most companies have multiple systems for managing content and sharing knowledge. From knowledge platforms, to social collaboration tools, wikis, and documentation systems, there is a lot of information already being stored.

Those are just the explicitly created knowledge stores. Then there are the systems with databases that are also storing bits of content. For developers, think project management systems, defect tracking, code repositories, service management apps, etc.

If that were not enough, you also have systems that pass along information. How much valuable content is hidden away in message threads on email chains? Communication is a simply a mechanism to exchange knowledge, making it a huge archive of information.

So the answer is yes, there are a lot of places that have knowledge. Yet developers are still working in an information-light environment because the useful and relevant content they need simply does not exist in any consistent or easily discoverable manner.

Image for post
Image for post

The solution to this has generally been a knowledge management project. The goal is to build a knowledge base to collect all of these disparate pools of knowledge. However that has not worked because there are no market dynamics to ensure long-term value of and trust in the content. What is required instead is an Information Architecture.

What is Information Architecture (IA)? Most practitioners come from the UX perspective in terms of designing websites or apps. However IA has a history going back to the 60’s:

“Conceptual structure and functional behavior, distinguishing the organization of data flows and controls, logical design, and physical implementation.” via “Architecture of the IBM System/360”

IA played an integral part of Xerox PARC behind their design philosophies:

“Perhaps because of the social nature of information creation and use, much of the technical research at PARC has emphasized the human-computer interaction and social aspects of computing.”

The emphasis is that IA is the higher level thinking of information separate from the physical manifestation of computing and that information has a built-in social layer.

This is still high-level though. Wikipedia has a more approachable definition:

“The art and science of organizing and labeling websites, intranets, online communities, and software to support findability and usability.”

This gets us closer to a practical knowledge solution. But how does wonky IA stuff specifically help developers find answers to internal questions more efficiently so that they can be more productive?

Early in my programming career, I was often roped into sales calls. To compensate for this affront to my career aspirations, they promoted me to “Solutions Architect”. However, I found that I enjoyed many of these sales conversations which often led to whiteboarding sessions where we mapped out application development and data flows for systems.

So let me whiteboard an approach to information architecture designed for developers.

  • Code Repository — system of record for changes over time to code
  • Community Platform — trusted market-based store of contextual content
  • Messaging Application — real-time communications hub across team
Image for post
Image for post

A brief explanation of the diagram is that code is the raw material and core intellectual capital of the development team. This is our first level content. The second level content are questions around that code, captured by the Community Platform. The third level content is the distribution, alerting, and search of code and content in the messaging app.

The conceptual framework for this approach is that code is where developers spend most of their time, so there should be a mechanism for capturing and sharing knowledge around code and discussions of that code. This is the Developer Knowledge Architecture.

The Developer Knowledge Architecture addresses the two core principles underlying IA. First, it is focused on the content rather than systems. Second, it adds the social layer through a community platform and a messaging infrastructure that accelerates and deepens adoption and engagement.

Where does monitoring, issues tracking, service desk, project management, or documentation? Those are important, but we do not want to boil the ocean with a huge waterfall like project. This is an agile and intuitive starting point to fulfilling the comprehensive strategy downstream.

What is important is getting started, building value and trust in the content, and addressing the most pressing productivity hurdles developers face today. The goal is to not just develop some all-encompassing knowledge base that no one uses, it is to give developers content that they actually care about and engage with regularly. Let me end with this:

“Most of the word information contains the word inform, so I call things information only if they inform me, not if they are just collections of data, of stuff.”
Richard Saul Wurman*

What do you think of this starting point for managing developer knowledge? What other content should be part of the knowledge architecture?

*Richard Saul Wurman is the person who coined “Information Architecture”, who is a fascinating human & the founder of the TED conference.

Image for post
Image for post

Why is there so much fear surrounding LiPo batteries?

Because my travel bag seems to be more batteries than clothes…

We help IT leaders in enterprises solve the cultural challenges involved in digital transformation and move towards a community based culture that delivers innovation and customer value faster. Learn more about our work here.

Written by

Thoughts on developers, digital transformation, enterprise agility, community building & software engineering culture. Author 👉 https://twitter.com/marksbirch

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store