Frontend code changes substantially, and often - and maintaining documentation becomes a chore that gets relegated to a low priority. This creates a knowledge gap that grows with each Git commit.
It's not all doom and gloom, though. Modern software development has produced some excellent dev tools that focus on creating better code documentation.
That's why I've compiled a list of 5 dev tools that will help you document your code like a pro. These tools have been carefully selected based on my own experiences as a developer, and they cater to different needs and preferences. Let's get started!
1. Swimm - Auto-Updating 'Walkthrough Documentation'
Swimm allows developers to create Markdown documentation easily with templates and auto-suggestions, and then find them exactly where they need it most - embedded right beside their code, inline, visible in the IDE (and GitHub!) itself. And best of all? Docs being coupled to the code means Swimm can auto-update examples in your docs whenever the relevant code implementation changes.
No more struggling with undocumented legacy code, repeated tours of patterns and dependencies every time a new person starts, or breaking out whiteboards to explain to your team how that incredibly specific microservice works.
Swimm's approach of coupling your documentation lets you create code-coupled docs that can provide notes and hints right in your IDE so that there's relevant documentation - already written - to review. And then Swimm lets you immediately jump in right from the link to the doc.
There are also a ton of additional features. Swimm lets you:
- Auto-update a centralized repository of docs with each pull request to your code.
- Integrate Swimm's tool into your CI/CD flow and send alerts whenever there are updates to your codebase that make embedded code snippets in your docs go out of sync. Swimm's patented algorithm analyzes what occurred and suggests auto-updates (Auto-syncs).
- Create 'Playlists' of documentation that walk new hires through your workflow, step by step, with code snippets - with all of it maintained using Swimm's Auto-sync, mentioned above.
ā Learn more about Swimm's Auto-sync feature
While some of the other options on this list try to provide generalized information to everyone within an organization, Swimm is very much catered towards tackling the pain point of knowledge sharing amongst development teams.
Whether it's knee-deep in the trenches of something such as React Hooks, or taking a 30,000-foot view of the codebase, using Swimm will amplify the level of internal dev support by several factors. Even with employee turnover, onboarding new hires becomes a breeze, which means they can add value to the company faster.
2. Guru - A Wiki for Company Knowledge
Documenting and sharing business knowledge (and yes, that includes patterns, workflows, and architectures of your code) requires more than just pooling all your information together and dumping it in a centralized location. In fact, that approach is what Ieads to your Notion page becoming a mish-mash of disorganized post-it notes and outdated lists.
Guru helps you cut through all of that by creating a centralized, searchable knowledge base - a wiki, if you will - for your entire company.
Have a complicated list of steps that must be followed to set up your dev environment? Turn it into Guru Cards and Collections - each task or process you have as part of the company's dev team could be a separate card.
Have a bunch of tips/workarounds/undocumented features for the architecture your app uses? Add tags to the collection so Guru can fetch them for anyone who needs them, at any time.
Need to chat to a coworker for help with something? @ them and ask a Question. The answer can be turned into a Card, and live on in the wiki for anyone on the team to access, whenever they need to look something up.
It's important to note that Guru is more focused on creating and sharing internal documentation and may not be as suitable for public-facing documentation.
3. Stack Overflow for Teams - Collaborate and Build Knowledge Bases Organically
Stack Overflow for Teams is literally just the Stack Overflow format, but for internal company knowledge instead.
Very different from maintained company wikis, because it isn't about stockpiling information that might be required, but instead, it's about providing a robust, indexed, structure within which one developer can ask a question, and another can answer, thus building up a repository of knowledge on code hacks, bundler optimizations, and ins and outs of the company's UI design system.
As an example, say your company workflow involves your Support teams needing to escalate issues to your UI/UX team. How do you do this without forcing your devs to deal with constant context switches to answer multiple questions which boil down to the same known issues, repeatedly, over multiple channels - Slack, Discord, email?
Using Stack Overflow for Teams, answer the question once and only once, mention related issues, and then use the Tagging feature to add this question to your knowledge base for posterity. Now, your Support teams can directly reference this knowledge base and never have to force engineers into productivity-ruining context switches, to do their jobs.
Once a question is answered, use the Collections feature to collate such questions, answers and even articles into one "collection" and store them in a central space where the entire team can access it.
Store longer-form content like project notes, spec documents, how-to guides, or post-mortems with the Articles feature. Ideal for onboarding new team members.
Stack Overflow for Teams fills in gaps that conventional documentation can't. While the latter is great as a repository of all features, functions, and variables used by an app, the former's question-and-answer format together with a dynamic, democratic nature where anyone can vote on answers, makes it ideal for solving a very specific organizational problem - building and maintaining knowledge bases in large-ish companies that have small, isolated teams who don't really know each other or talk much, but just happen to share office space - where cooperation might be difficult.
4. Slab - Streamlined Customer Feedback
Today's ultra-competitive landscape of web development means you will get left in the dust if you don't place an equal importance on user feedback.
Slab is a centralized "knowledge hub" that simplifies the process of managing customer feedback, allowing developers to better understand and act on user feedback and improve their software.
Slab lets developers Document, collect and organize end-user feedback from a variety of sources, such as email, social media, and in-app feedback in a centralized manner. Developers can use such feedback to make informed decisions about how to improve the application.
Developers can use Slab's integration with Github, Trello, Slack, Jira, Google Drive, and dozens of other platforms to track and prioritize user feedback and link it to their app. Developers can then easily reference such feedback when updating their application - and use it to identify which features are most valuable to customers.
Slab creates a documentation portal for publishing articles, tutorials and feedback systems for developers to improve documentation. Team members can collaborate by assigning tasks and commenting on feedback. Information is automatically organized and contextually linked by Slab.
Slab may not have advanced features and customization options; but it's a nice choice for devs looking to improve the functionality and end-user experience of their applications.
5. Confluence - Bridging the Gap Between Devs and Non-Devs.
For most projects, keeping knowledge bases as Docs-in-Repo will work perfectly fine, but when you grow large enough, this approach is a one-stop shop to ensure they're never seen by people who aren't developers, but who need that access regardless.
Confluence - well known among developers as a versatile, collaborative, feature-packed workspace - is what bridges the gap in just such a scenario. While you can definitely put detailed, code-heavy notes in here, Confluence's potential becomes apparent when you need to store code-tangential knowledge.
Imagine there are internal discussions and notes on license agreements for third-party libraries, or negotiations with patent holders for technologies like video players for your web app. Non-devs (like your Legal team) can access this information, comment on and add to it. Confluence enables them to do just that (and open it up to devs as well) without having to go through Git peer reviews.
Confluence addresses the pain points of documentation by providing a simple and intuitive editor that allows devs and non-devs alike to start working on documentation quickly, with features like headings, images, tables, lists, and more. There are collaborative features such as spaces, real-time editing, commenting, sharing and notifications.
It's a nice option for large organizations, with scalability that allows it to be used by small teams and enterprise-level organizations (with up to 200,000+ users) alike, and extendability through the Atlassian Marketplace which offers plugins and extensions.
However, Confluence is also a lot more expensive than the other tools on this list, and hence not as suitable for small projects, startups, or organizations where purchase authority is strictly rationed.
Conclusion
Swimm is the best solution for making sure your docs stay up to date and in sync, with its code-coupled documentation approach together with Playlists, and an easy integration into your CI/CD pipeline. You could even use it together with something like Confluence to make documentation accessible to everyone, Stack Overflow for Teams to enable internal discussions in a vote-based question-and-answer format, and Slab to be efficient with your user feedback.
Together, these tools offer powerful collaboration features, inline documentation, and integration with other platforms, making it easier to keep your documentation up to date and accessible.
