How to promote a new tool
This is a part of our use case guide series, exploring how code-coupled documents can help engineering teams thrive.
When introducing a new tool or library, engineering teams often need to quickly adopt the best practices related to this new tool. Best practices stem from experience, and understanding what works well and what doesn't. Adhering to best practices can help avoid mistakes but promoting them across organizations can be challenging, especially over time. Using code-coupled documents can significantly help software development teams promote best practices.
General considerations when promoting a new tool
Developers are often overwhelmed with different tools they need to know and use. Be clear about the motivation for introducing a new tool. Why is it important that you use this tool and not implement the functionality yourself?
Each third-party tool comes with its caveats - dos and don'ts. When using a third-party in your codebase, best practices documentation state specifically how and why you use it. This information is rarely found in the library's external documentation. If it is - it's hard to find because it is surrounded by generic details that do not apply to our specific use cases. Furthermore, using all of the functionality within a third-party is very rare, so we focus on a subset of this library's functionality - the functionality that is used within the codebase.
When using a wrapper to hide most of the internal details of how we use the third-party library, it's important to describe how to use it including how it operates and what underlying assumptions were made when implementing it.
Use an example
The best way to explain how to use a new tool or library is by demonstrating it. Even if you have just implemented the wrapper, implement a first usage example yourself before sharing the tool with others.
Perhaps the most important part is to find a good example of using the tool. Note it should be a real example from your codebase rather than a made-up example with pseudo-code. You may need to write such an example if it doesn't exist already.
Why a (real) example?
- It's easy to understand. As a developer, a real example is easy to relate to. It also provides a good basis to rely on when the developer would look to use the tool themselves.
- It's easy to create such a document. If an example already exists in your codebase, there's no need to invent a new one. All you have to do is describe it.
- It helps you remember. When you look at a concrete, real example - you see all the small implementation details. Not all of them are important to mention or explain, yet it makes sure you don't forget about those that are.
- It's maintainable. By code coupling to an existing example, if something ever changes in the system and the example changes, your document will be updated.
- It's easy to discover. Thanks to the discoverability of Swimm documents, they are found when someone uses this tool. For example, when using a library for the first time, a developer may look for other usages of this library in the codebase, such as the wrapper function. Thanks to Swimm's IDE plugins, developers are likely to find the relevant document next to the wrapper function because it was referenced and code-coupled in the document.
What should your document include?
A general explanation of this library:
- Its purpose.
- Why and how we use it in our codebase (a short description).
- A link to its external documentation.
Additional things to include
- Provide a concrete usage example from the codebase. Mention the important functions that are used. This should be the main example as described above.
- Describe the best practices - dos and don'ts, regarding the usage of this library in our codebase. When there are specific assumptions or tweaks for the use case of this specific codebase, mention them. For example, if you have used a workaround to make something work differently than intended - be sure to mention it here.
- Specific configuration details or parameters we pass to the library's API for some reason.
- If there is a wrapper, explain where it is located in the code, how it is used (provide an example, and how it's implemented.
This document is automatically kept up to date using Swimm.