You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
Version 1
Next »
Interfaces document how elements of the system communicate with elements of this and other systems.
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:
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).
The value is edited by the use of the Interface Type Macro.
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
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.
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.
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.
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.
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.
Document the technical protocols.