Documenting technical standards
Make your technical standard a success
Your organization is developing a technical standard that supports companies in your industry with interfaces, database formats, exchange formats or frameworks. How well a standard is applied also depends on how good the documentation is, especially the specification.
Excellent documentation can be instrumental in helping a technical standard become accepted and accelerating interoperability.
We document your technical standard
We are an experienced provider of documentation services for technical standards. We explain the basic structures of your standard and its application rules in the specification. We distinguish clearly between descriptive content, examples, and technical or business rules that require or enable a specific implementation. If you wish, we can create test case descriptions to enable automatic validation of rules.
Our documentation includes examples that show how to apply the standard as well as use cases, tutorials, and code samples, all of which help minimize doubts and questions. This is how we work.
Your contacts
Documentation of technical standards
Our customers
Documentation of technical standards. This is how we work
- Learn about your standard. We get to know your standard and its users.
- Clarify your goals. We determine your strategic goals regarding content management and adoption of your standard.
- Apply and customize information architecture. We use our proven information architecture for technical standards, with concept structures, reference information, rules, use cases, and code examples. Upon request, we will customize the information architecture to meet your needs.
- Document the standard. Together with your subject-matter experts, we document your technical standard in English or German.
- Support development. We help developers with the modeling and technical implementation of business requirements. This includes terminology work, code documentation review, and visualization.
- Define terminology and writing rules: We define language rules and apply them to the specification. We review the language and terminology of all content to make sure that the specification is consistent and easy to understand.
Learn more about the documentation of technical standards in our FAQs.
FAQs – Frequently asked questions about documenting technical standards
Why is it important to document technical standards?
When a technical standard is clearly and accurately documented, users can understand the standard and apply it in their own solutions.
Standards are often associated with security concerns. Precise documentation ensures proper implementation of standards and evaluation of any potential security risks.
For an organization that creates technical standards, technical documentation can help uncover gaps and any room for interpretation in the standard. Documentation also ensures that everyone involved in developing the standard is speaking the same language.
What is important when documenting technical standards?
Documentation is complete
- Includes all information necessary to understand and apply the standard.
Documentation is clearly written, up-to-date, consistent, and comprehensible
-
Is written clearly and precisely to avoid misunderstandings. This includes clear descriptions of mandatory and optional rules and recommendations. See also Swagger OpenAPI specification, RFC2119, or RFC8174.
-
Is up-to-date and includes all relevant changes
-
Uses a consistent language and terminology.
-
Defines all important technical and business concepts of the standard.
-
Is understandable to the target audience.
Documentation is applicable
-
Includes real-world examples and use cases.
Documentation is accessible
-
Is easily accessible. Users and experts can quickly find the information they need and there are no barriers to implementation.
What are good examples of technical standards documentation?
- Documentation on the World Wide Web Consortium's (W3C) CSS validator. The documentation is known for its clarity and ease of use; and includes examples as well as implementation instructions.