Tommorow, Not Today
As with many classes, topics, and projects I have been a part of for the last few years, I see a consistent pattern. The unwavering focus on what’s going on in the present and never connecting the dots on how something might benefit me in the future.
Code documentation is just one of the many examples I could come up with to further my point. Up until now, all my work has followed the motto of “me, myself, and I,” failing to see that in the future that won’t be the case. Eventually, everyone will find themselves a part of a team, and there is nothing worse than an amateur teammate. Let’s take a deeper look into code documentation and why it will eventually be an asset to not just you but also your future teammates.
Type of Code Documentation
Internal Code Documentation: Intended for developers inside the organization.
- Process Documentation: Provides high-level information like product requirements, roadmaps, notes, and reports.
- Developer Documentation: Provides detailed instructions for developers and staff for building, testing, deploying, or maintaining the software.
External Code Documentation: Intended for developers outside the organization who integrate with the product or need to understand its code.
- External Developer Documentation: Provides essential instructions for using source code, integrating with a product, and leveraging developer interfaces like APIs and CLIs.
- Enterprise Documentation: Furnishes information for IT staff involved in software deployment, covering hardware requirements, sizing, operational needs, and maintenance guidelines.
- Usage Documentation: Guides non-developer users on product utilization without relying on programmatic interfaces. Describes main functionalities within the product’s UI.
- Just-in-Time Documentation: Supports developers as needed, often in the form of knowledge base articles, FAQ pages, or blog posts, added in response to new features or requirements.
Low-Level or Inline Documentation: Resides within the source code and explains details of specific code parts in isolation, such as the purpose of certain functions and arguments.
High-Level Documentation: Describes the architecture, design principles, implementation guidelines, or other broader concerns.
Walkthrough Documentation: Describes flows, patterns, and other important parts of the codebase, especially for developers who need to contribute to the code.
Food for Thought
Documentation might seem straightforward, but there are some issues that must be considered whenever starting a new document.
- Knowing Your Audience: Depending on why/who you are writing your documentation for, you must consider their level of understanding when it comes to your subject.
- Updating Documentation: It is very easy to push changes to your software and forget to also push changes to documentation. This starts a cycle with co-workers where the documentation falls behind and becomes uncomprehensible.
Tommorow
Embracing comprehensive code documentation is not just a practice for today but an investment in our collective future. As we transition from individual contributors to collaborative team members, the value of clear, well-maintained documentation becomes vital to future projects.
From the blog CS@Worcester – CS: Start to Finish by mrjfatal and used with permission of the author. All other rights reserved by the author.