- Created by Robert Reiner, last modified on 20. Jan 2019
projectdoc Toolbox
Interfaces document how elements of the system communicate with elements of this and other systems.
- ID
interface- Suite
- Documentation Type
- Categories
- Tags
Description
Interfaces document how elements of the system communicate with elements of this and other systems.
Properties
The document type interface provides the following properties:
Please note that only information about specific properties is provided here. Common document property used by all document types are documented by Document Properties.
Identifier
Define the unique technical identifier of the interface.
Version
Specify the version of the interface that is described by this document.
Type
Define the type of the interface which may be internal (used by components of the system you design) or external (also used by components outside the system you design).
Level
The level is relevant if you want to document an interface by individual parts.
Reference
Add references to information on external systems here. This is useful if the documentation for an interface is defined elsewhere or may be provided by the interface on-demand.
Sections
Description
Give a summary on the interface.
Business Context
Describe the functionality of the interface from the business point of view.
Business Processes
Describe the business processes relevant for this interface.
Interface Data
Describe the data in its technical context.
Requirements
List the requirements on the interface.
Security Aspects
Describe the security aspects to consider when publishing and using the interface.
Quantities
Define the quantities serviced by this interface. This addresses figures concerned e.g. with
- Runtime
- Throughput/Volume
- Availability
- Logging
- Archiving
Participating Resources
Resources affected when this interface is used.
Syntax
Data and Formats
Define the data formats, validity and plausibility rules, encoding, character sets, and configuration data.
Methods/Functions
Describe the methods to check data.
Sematics
Describe the side effects and consequences.
Technical Infrastructure
Document the technical protocols.
Error and Exception Handling
Document the codes and handling of error and exception cases.
Constraints and Assumptions
Document access rights, temporal constraints, parallel access, and preconditions for using the interface.
Operating the Interface
Document the interface from the operation point of view.
Meta Information
Document the person in charge, costs of using the interface, organizational issues, and versioning.
Architecture Decisions
Document the architectural decisions made for the interface.
Examples of Using the Interface
Provide some examples to help users to get started with using the interface.
This may be use cases as well as coding examples.
Subordinate Interfaces
Complex interfaces may be subdivided into single interfaces.
Notes
These are internal notes that are usually not exported and only visible to team members with write access.
But this is not a safe place to store sensible information. It is just a convenience for the reader to not be bothered with notes stored here for the authors for later use. The security level is about suppressing the representation by a CSS style. Therefore consider this as a convenience for the reader, not as a security tool.
The text of notes sections is also indexed.
References
For a document the references section contains pointers to resources that prove the statements of the document.
Often these proofs are not easily distinguishable from further information. In this case you may want to skip the reference section in favour for the resource list.
For further information please refer to References and Resources.
Resources
The resources section provides references to further information to the topic of the document.
This may be information on the internet provided by the resource or information in the team's information systems. Anything the reader of the resource might want to know, may be listed here.
For further information please refer to References and Resources.
Details
This doctype is based on information provided by the arc42 Template.
