§ 17 Makers' Guidance

Context

Developers make use of tools in their work and, as such, should know how to work with them, using effectively their features to make the best use out of their capabilities. Having Adequate Skills is paramount to this, and they can be achieved through employing a mix of approaches, including Practice Makes Perfect, Written Knowledge, and Learning From A Master.

Problem

Skill development, regardless of the approach in use, requires a source of knowledge from which the learning is derived. It is important that that information has a high quality, in order to ensure developers learn good practices and do not end up with bad habits or gaps in their knowledge.

How can we find knowledge to support our learning about the tools we use?

Forces

• Developers may want to use a specialised, niche, or custom software solution because it may be the best fit for their needs, but these tools often have fewer community-made resources, resulting in the tool makers becoming the main sources of information and documentation.
• Resources made by the tool makers are informative about the tools’ features and intended behaviour, but they may lack practical tips and knowledge present in community-made resources that come from real-world use.
• Time, budget, and institutional support enables developers to access structured learning opportunities such as certifications and workshops, but these resources may not be aligned with the developers’ current needs or their learning style, dampening their effectiveness.

Solution

Seek out and incorporate learning resources made by the developers of the tools, such as tutorials, documentation, and other forms of information, into your learning process.

Tool makers are in a position where they can provide authoritative and comprehensive information about their products, as they possess insider knowledge of how their tools are designed and how they intended them to be used. As such, the tool makers can communicate concepts about their software solutions in a precise and structured manner, potentially taking many forms such as function references and programming guides. These provide developers with a reliable foundation for learning what the tool can do and how it was meant by the tool makers to be used.

Official resources are maintained alongside the tool’s lifecycle, enabling developers to be sure they’re consulting up-to-date information even as new versions of the software come out. Many tools include versioned documentation, changelogs, and migration guides, making it possible for developers to stay well-informed even if they are using an older version.

In addition, tool makers often provide more interactive materials to help developers improve their skills. These can take the form of guided tutorials, self-paced video courses, or certificate programmes. These resources enable developers to translate the tool’s conceptual design into practical, goal-oriented learning.

Finally, maker-produced resources have value in how they create a shared vocabulary related to the tool across different organisations. Relying on a common, authoritative source improves communication between developers and stakeholders by bringing in consistent terminology, in turn reducing friction and potential misunderstandings. This shared language becomes more essential in collaborative environments or regulated contexts, where clarity and traceability are important.

Examples

• Official documentation, such as function reference pages and API guides are usually published by tool makers, providing developers with an easily accessible and canonical source of information for them to consult when needed. These materials serve as a source of Written Knowledge^[1].
• Tutorials, courses, and certifications offered by the tool makers provide developers with guided, step-by-step learning paths, supporting Learning From A Master and Practice Makes Perfect.
• Some vendors also host events where developers can interact directly with the tool makers in webinars, Q&A sessions, and and workshops, potentially building Stakeholder Relationships.

Consequences

• High-quality documentation enables developers to be more knowledgeable about their tools, enabling building Adequate Skills.
• Even if the tools in use are very niche or a custom solution, the chances that their makers left behind documentation on them is a good one, ensuring their users don’t have to figure out things by trial and error.
• The tool makers are the authority on the tool regarding its function and behaviour, but they may, unlike the community around the tool, be unaware of potential edge cases or challenges that stem from real-world use. Developers may want to turn to It Takes A Village to learn more from the community.
• Some official resources, such as certifications, may be too costly for the developer’s organisation.

Related Patterns

This pattern provides a contrasting approach to §16 It Takes A Village regarding skill building.

This pattern details one of the ways developers can find information to support their skill building process using §13 Practice Makes Perfect, §14 Learning From A Master and §15 Written Knowledge.