Our previous article on reuse basics described how your team could benefit from developing with reuse in mind. As you start adopting reuse content in your development environment, ensure that your code and content include the following seven characteristics.
1. State the benefit
Before you share reusable content, ask yourself the following questions:
- What does reuse mean for this construct?
- Can you explain why and where this asset or code adds value?
If you can include supporting testimony from an open-source community, vendor, or other consumers of the component, then it strengthens the weight of your reuse.
2. Define the target audience
To share reusable content or code, you must understand and define your target audience. Ensuring who would use your content and what they are trying to accomplish helps you ensure your content or code will have maximum effect.
Does it benefit application developers, architects, infrastructure engineers, or another audience? What phase of the Software Development Life Cycle (SDLC) would this help—design, build, delivery, operations?
3. Ensure the solution is well documented
Reusable components need to be sufficiently well documented so the target audience can easily consume them with little to no assistance. Consider including the following in your documentation:
- Clearly identify inputs and outputs. Use standard contexts like Swagger to cleanly describe interface contracts.
- Highlight dependencies, including version numbers of those dependencies that the published solution relies on. Are there supporting tools required to build or deliver the solution?
- Ensure parameter types, ranges, and acceptable values are all clearly documented. Clearly state the functional impact of parameters as they change and any relationships between the parameters and their impact on the behavior. Ensure the solution is sufficiently parameterized to support most common use cases.
- Provide usage examples of the component. It's even better if you can include examples supporting multiple languages or delivery mechanisms. For example, show an algorithm written in both Java or Python, or show a configuration management recipe in both Terraform and Ansible.
- Identify constraints. Where applicable, identify any unique build constructs or constraints for the solution.
- Is there a group already using the solution? Point consumers to reference implementations whenever possible to facilitate their implementation and foster collaboration between teams.
- Collect feedback. Provide a mechanism such as GitHub issues to get feedback for improvements and bugs and document any potential issues consumers may need to address. Place common issues into a Frequently Asked Questions (FAQ) sheet that provides solutions and implementation details.
4. Address core engineering principles
As you deliver reusable components, ensure that core engineering principles are addressed. Avoid making your audience figure out how to implement these core principles in your solution.
Some items to consider:
- Security: Does the solution implement current security standards or is it intended to be used within a standard security context? Specify protocols, Role Based Access Controls (RBAC), certificates, JSON Web Tokens (JWT), and service accounts that may be part of the implementation.
- Observability: Is the solution sufficiently observable? This may already be 'built-in' using existing observability tools such as a Instana or App Dynamics (AppD). If the solution requires customization of any kind to get key metrics, ensure that customization is well documented. Bonus points if you can show what 'good' and what 'not good' look like and what thresholds consumers should consider.
- Design: If the solution is a concrete implementation of a pattern, include a reference to the pattern. Ensure bounded contexts are identified if applicable. Highlight where security contexts and boundaries are and what makes it modular, encapsulated and loosely coupled.
5. Specify ownership and support
Clearly define who owns or supports the code or content asset.
- Is this an open source or inner source solution? Provide a link to the community.
- Is this a consumable API supported by a fully staffed product team? Provide onboarding links, issue assignment groups, and escalation procedures.
- Is this provided 'as-is?' Let users know they are free to modify, augment, enhance, fork, etc.
6. Remove duplicate content
If there are others with similar solutions already in place, can one be the 'champion' and reduce the number of possible solutions and documentation consumers must wade through? Be sure to reference any other implementations that solve the same problem with different tools or languages. Better still, see if you can merge the repositories in a single solution.
Don't duplicate already published content either internally or externally, provide a link to it instead.
7. Respect original sources
Give credit where credit is due. If you are enhancing a solution for reuse that you don't currently own, ensure that you're giving credit where it's due. Make sure you reference original authors.
Conclusion
Using and creating reusable code and content assets reduces duplicate effort for your engineers and developers and ensures consistency of code use and development practices. When creating reusable content or code assets, ensure that the asset meets the need of a specific audience and its benefit is clear. Thoroughly document your solution and ensure that it includes core engineering principles. Merge assets or code that are similar so that readers have a sole source of truth to work from. Finally, ensure that ownership is clearly defined and cite original sources, when appropriate.
