The cover image for this post is by Sigmund
This is part six in our series of blog posts detailing our system for genius when working safely with legacy code. The other parts of this series include:
- A Series On Safely Navigating Software’s Timeless Artifacts
- Preparing To Tame Legacy Code With User-Led Odysseys
- Conversations with Code Custodians
- Why Documentation is Key to Legacy Code Success
- Before Running the Build
Introduction
As developers, we often find ourselves navigating through complex codebases. These legacy systems can be daunting and confusing, making it essential to document our findings throughout the process. In this blog post, we will discuss the importance of creating a digital single source of truth for all knowledge about the system. We will explore various tools that make documentation more manageable, such as Visual Studio Code with the Microsoft Learn authoring pack, Obsidian, and services like Confluence and Notion.
Throughout the series so far, you may have gained valuable insights about the codebase but not yet developed it on your machine. This crucial step highlights the importance of documenting everything learned about the codebase before working on it yourself. Transform these notes into an accessible format for your team and ensure they are source-controlled to facilitate seamless collaboration and future enhancements.
Documentation
Before beginning any work, request a new repository in the team’s source control provider, this will be used exclusively for the documentation. This allows you to share findings and collaborate with other team members on the same platform, as well as store notes in source control for easy access, versioning, and tracking of changes.
By storing your notes in source control, it ensures the information remains accessible, up-to-date, and secure for all team members involved in the project. In case of machine failure or data loss, having your documentation stored in a centralized location prevents critical information from being lost and allows for seamless collaboration among teammates.
As you analyze the codebase, take detailed notes in plaintext or Markdown format. Organize this information using branches or tags for easy navigation. These notes can be taken in a variety of formats, such as digital (text files, eInk scribblings), physical (pen and paper), or even audio recordings of you talking through your thoughts. By digitizing these notes and storing them in your newly created repository, you can easily share findings, collaborate with other team members, and maintain a cohesive understanding of the system’s inner workings. This digital single source of truth enables developers to keep track of progress, learn from past mistakes, and continue to improve the documentation for future developments.
Collaboration
Share your findings, solutions, and goals for the system with other team members to ensure everyone stays aligned during the development process. By incorporating continuous communication and collaboration into your workflow, you can minimize misunderstandings and keep all stakeholders on the same page. Additionally, asking other maintainers of the codebase to review your documentation as you progress will not only gather valuable feedback but also uncover new information about the system that was previously unknown or underestimated. This open communication helps build a stronger foundation for future development and continuous improvement within the team.
Organize notes with summaries and links to both internal and external resources to create a comprehensive knowledge base. This makes it easier for others to learn from your work, build upon it, and continuously improve the documentation. By keeping the repository well-structured, easily searchable, and up-to-date, you increase the likelihood of other developers contributing to it in the future. Additionally, this organized approach ensures that valuable information is never lost or overlooked as team members transition in and out of projects - such as the SDK, framework, and tool versions required to build and run the code.
Tools for Documentation and Collaboration
As plaintext or Markdown formatted text has become the industry standard for documentation in codebases, IDEs like Visual Studio Code and applications like Sublime Text have taken over where applications like Microsoft Word used to be top of the mountain. This shift to plaintext ensures that documentation can be easily placed into source control for seamless collaboration among team members.
Microsoft’s Learn authoring pack for VS Code offers additional benefits such as a spell checker (with customizable language settings) and tools like Markdown formatting checkers and a basic linter, ensuring high-quality documentation across the board.
When those tools just won’t cut it anymore, consider using Obsidian, a powerful tool that utilizes Markdown and the concept of ‘vaults.’ These vaults provide a logical separation for your groups of files (think of them like repositories, but for your markdown projects), allowing you to easily switch between projects on the fly. With its extensive plugin ecosystem, Obsidian supports integrations with source control systems, theme customization, knowledge graph creation, and PDF export capabilities.
Also consider using platforms like Confluence and Notion for online documentation storage, as they offer built-in features that resemble source control while integrating seamlessly with other organization tools. These platforms can be especially valuable if your team already utilizes Jira or other Atlassian products, allowing for direct referencing of Confluence pages within Jira tickets.
Continuous Integration/Continuous Deployment (CI/CD) Practices
Setting up DevOps actions for the documentation repository isn’t necessarily required during the initial stages of note-taking and organization. While CI/CD pipelines and automated actions like producing PDFs and emailing them to team members may prove useful, it is essential to prioritize digitizing your notes in source control first. By focusing on capturing and storing your thoughts within an easily accessible format, you can create a solid foundation for future improvements and enhancements without getting bogged down in complex tooling setups.
In Conclusion
Documenting your progress while working with a complex codebase is vital for efficiency and collaboration. Utilizing the right tools and practices will make the documentation process more manageable and ensure smooth collaboration between team members. Furthermore, understanding CI/CD practices will be advantageous in the future when implementing changes and updates to your legacy system. By following these guidelines, you can navigate complex codebases with ease and maintain a digital single source of truth for all relevant information.
Stay tuned for the upcoming chapters as we delve further into the art of deciphering legacy code and navigating the intricacies of software archaeology.
If you’d like us to help you work through the challenges involved with working safely with a legacy codebase, either in a hands-on capacity or as a consultant, get in touch with the form below