In a previous post, we bootstrapped some thoughts about what knowledge was useful for developers in their work. Also, we discussed that each piece of knowledge has its specificities (when and how it’s hit, how often it’s updated, how critical it is to notify the audience, …).
In this post, we propose a cartography of 20 different types of knowledge and information sources that developers interact with during their work. This might help you structure your team’s onboarding process of new developers and ensure they have access to the data they need to succeed. Or, if you just joined a new company, you can use it as a checklist to see if you’ve got all the access you need. This isn’t exhaustive, and you may identify more knowledge sources — Let us know! Also, we list a few examples of tools; some more exist.
#1 The How-to procedures, tutorials, and Get started guides
Helpful for setting up software or project on a laptop, when configuring your IDE for the first time, when we need to connect to a remote database, bootstrapping a new project according to a specific skeleton, or how to ship a new version of the app. A small group maintains this documentation, which is often a one-time read procedure, as you won’t need it every day. But we’re happy to have it when we need it. We also call them evergreen content. Tools: Confluence, Notion.
#2 Best coding practices
Developers’ gestures in writing source code according to the team practices. This is about properly writing the source code in the developer’s context. These best practices should be precisely defined in a team and at the company level, continuously maintained, and regularly discussed. Integration during code reviews and in the IDE are a must-have. Tools: Packmind.
#3 Code documentation
Get insights on the code base, a sub-part, or a particular code snippet. It can help to understand complex behavior, a past non-intuitive technical choice, or an implementation detail that needs explanations. Use it carefully, as it’s best practice to have a self-explanatory code where comments don’t bring value. This code documentation is usually contextual, and developers should keep it up-to-date. Tools: Swimm, Read the Docs.
#4 Tests suites
Test code is a powerful documentation of the code, and we could quote it in the previous bullet #3. Reading test code gives an overview of the core methods of your software and gives concrete examples of usage, especially if your team writes tests using the Given/When/Then or Arrange/Act/Assert patterns. If you dive into a new module, looking for tests is a great start to becoming more familiar with the code base. Tools: your favorite test framework, JUnit, Mocha, PyTest.
#5 API Documentation
An unavoidable one, it helps you understand how to use an SDK or an API, discover the available services and their purpose, and how to interact with them programmatically. The code examples give you confidence in using the API and handling situations when errors happen. At first glance, you should detect whether or not the API satisfies your needs. Otherwise, go your way. Tools: Swagger, Doxygen, apiDoc, Readme.
#6 The code quality issues
Check if the source code contains security issues, bad smells, formatting troubles, readability improvements, and more, with source code static analysis. You can have feedback on your IDE during a code review and a global overview in a dedicated dashboard. These linters are available for all programming languages and help keep the code syntax consistent. Tools: SonarQube, Codiga, EsLint.
#7 User Stories
Help understand a future feature to be implemented, its intent, and the purpose for the users. A user story (US) contains the requirements and specifies the acceptance criteria to clarify how to consider the feature ready. The US is a communication bridge between a product owner and a developer, as all content is recorded. A must-have to start coding! Tools: Jira, Trello, Asana.
#8 Bug reports
They have two main goals: 1) Get information about a newly notified bug, how it impacts the users, what its consequences are, what the error messages available are, and how to reproduce it 2) Find information on a previously fixed bug, as we currently investigate a similar one; you search how this previous bug was fixed, to help you in your work. They’re crucial to ensure the bug is fixed and to implement countermeasures. Tools: Linear, Jira.
#9 Executable specifications
Behavior-Driven Development (BDD) helps generate scenarios that illustrate business domain use cases from which you can establish business rules. Business experts, developers, and stakeholders (such as QA engineers) have co-built the concrete behavior examples. You can formulate these examples with the Gherkin syntax. During your onboarding, these examples help you to get familiar with the business domain. It drives the coding process, especially when using TDD. Tools: Cucumber, Cukedoctor.
#10 Architectural schemas
This high-level material can sum up a software project's big picture, the main components, and how they interact together. It’s useful when onboarding a new project to understand better how things work. Diagram flows or UML schemas can also document the software at a high level of abstraction. It can be inappropriate for some software, as you can self-document an adequate code architecture. Retro-engineering and code analysis can also provide insights into the code's architecture. Tools: Notion, CodeSee.
#11 The technical debt overview
I take a shortcut with the term “technical debt” to consider the parts of the code that require a rework — not only because the code is complex, but because the implementation, as it is, might raise issues in the short/middle term if nothing changes. The overview of the source code parts annotated as tech debt can help prioritize remediation and estimate the effort to provide. Tools: StepSize, CodeScene.
#12 Answers to a technical issue
Not easy to categorize, but here I refer to every blocking issue we face when coding or building the application, such as a compilation issue. When you’re stuck and can’t find an answer in the documentation, you can use async channels to ask if someone has met a similar problem. The answer unblocks the workflow, and you can resume your job. You can find the answer inside the company or over the internet. Tools: StackOverflow, Slack, CodeStream.
#13 Architectural Decision Records (ADR)
An ADR is a document that captures essential decisions such as design choices, trade-offs, and rationales related to the architecture of the software. It serves as a historical record and provides transparency and accountability for architectural decisions. An ADR also gives information about its context and its consequences. Helpful when you join a project to get insights into the architecture evolution. Tools: Markdown files embedded in the Git repo.
#14 UI Prototypes
Front-end developers are keen on consuming UI prototypes that reflect what’s expected regarding user interface and screens. It helps understand the user workflow and provides a clear overview of the user experience on the feature under development. They’re necessary to get started with the design implementation, accessing CSS elements, and producing a result that matches precisely the prototypes. Tools: Figma, Adobe XD.
#15 Design System
A system to centralize and reuse components related to the design of a product, a domain, or a company. Mainly helpful for front-end developers to ensure they ship source code with up-to-date design elements (logo, font, icons, …). Known as a central place where we can find information related to design decisions. Tools: Storybook.
#16 Runtime logs
They give valuable information on the runtime behaviors of your code. They help you investigate a bug report or analyze the performance of your software. Logs are essential for the observability of our software, and they provide precious insights into what happens in practice (how many times a service is called, how long last a service execution, …). All developers should have access to the logs in production. Tools: Logtail, Logz.io, Loggly.
#17 Code history
Helpful when you need to understand how a piece of code came up to its current state or if you realize the state has changed from the last time you saw this code and would like to know what happened. Versioning with Git provides excellent support and sometimes brings you to archeology work. You can identify the latest editor of a code and get in touch with him/her for further questions. The previous commits also give visibility to the current work. Tools: Any Git client*,* GitHub, GitKraken, GitLab.
#18 Build statuses
Hit by a developer to check if the branch merging doesn’t raise any issues or to get more information about a broken build (likely to be a failed test). This information is read on-demand and usually not on every push on the Git repository since alerting systems send notifications when there’s an issue (and not when all is fine). The build status indicates whether the code is ready for production. Tools: Jenkins, GitLab CI, GitHub Actions.
#19 Learning resources
Developers can learn from their current projects and grow personal skills in specific concepts in parallel. E-learning resources allow async learning sessions to be completed when it suits your planning. Practice sessions are helpful in training on a new language you’d like to progress on. For instance, we also include blog posts shared in internal channels within a Community of Practice. It’s part of the continuous improvement process and the learning culture. Tools: Pluralsight, Udemy, Internal wikis, books.
#20 Product documentation
Often forgotten, it still gives precious information on how the software behaves and helps to understand the application's different use cases and user workflows. It makes sense if the software is quite complex. Technical writers maintain this documentation; you might do it in some context. Tools: GitBook, Intercom, Zendesk.
Wrapping up
We’re done with this list! One last question for you now: how many sources do you have access to among this list? Do you have more suggestions? We’d be happy to add them, especially if you regularly hit some information or knowledge not mentioned in this post. Thanks!
Top comments (0)