Wiki Documentation Overview
Summary
Wiki document describing the documentation that should be created for each product present in a TKU release.
The documentation forms an important part of the deliverables as it's responsible for describing the product and module to the customer, demonstrating how we identify, version and model the product and how we have verified it.
Components of the documentation
There are nine major headings for the documentation, within in these sections you should go into more specific details on the subject:
- Product Description
- Software Pattern Summary
- Platforms Supported by the Pattern
- Identification
- Versioning
- Application Model Produced by Software Pattern
- Differences to 6.x approach
- Subject Matter Expertise
- Testing
- Information Sources
- Open Issues
Product Description
The product description should describe the product and its features, in addition you should identify versions of the product that we are aware of.
Software Pattern Summary
A summary of the SI types that could be created by the module should be entered here along with OS Type(s) and Versioning summary.
Platforms Supported by the Pattern
A brief description of the platforms that are supported by the module.
Identification
The identification section should contain information on how we trigger the patterns, it should document the Directly Discovered Data Node that is triggered on, it's attribute (if any), the condition (equality, less than) and the value it should compare.
Finally a brief summary of any Simple Identities that are created by the pattern.
Versioning
The versioning section should have unique sections for each of the versioning techniques that are used:
- Active Versioning
- Path Versioning
- Registry Versioning
- Package Versioning
If there is more than one instance of a specific technique then you should have additional sections documenting the specific technique.
Within each subsection you should describe the technique, an example of how it would be executed, the OS's that are supported, the level of depth achieved and its reliability.
You can also have sections for Alternative Versioning Techniques that have not been used within the pattern for whatever reason and Future Considerations that should be taked into account when updating the pattern in the future.
Application Model Produced by Software Pattern
This section should discuss the overall structure of the application and how we create our Software Instance model, the following sections are usually used:
- Product Architecture
- SI Depth
- Software Pattern Model
- Relationship Creation
- Future Consideration
The Product Architecture should describe how the product is run and how it appears on the system, for example does it fork and have children, what are the unique characteristics of related processes, etc...
Pattern Trigger...is this required again, it is already documented in the Identification section?
SI Depth includes a description of how deep the created Software Instance is, and what is included in the key to ensure that it is unique.
The Software Pattern Model should include a description of the model created by the module and how it relates itself to any other supporting or related processes.
It should also document any special conditions in the body that may cause some triggered patterns to stop immediately.
Finally you should describe how we derive the key or key_group for the software, if any active techniques are used then these should be clearly stated to ensure easy identification.
Future Considerations, this section should contain any thoughts on how we can improve the modelling of the product in a future release.
Differences to 6.x approach
This section should contain a description of how the pattern has been improved from the 6.x SE Matcher.
Subject Matter Expertise
This section should indicate what feedback has been received and how we have incorporated any comments into the pattern.
Testing
You should finally document how the pattern was tested, what platform it was tested on and whether it was a live scan or if record data was used.
Information Sources
In this section you should briefly describe and link to, if possible, any information sources that were used to create the pattern and supporting documentation.
Open Issues
This section should describe any outstanding issues against the pattern, any thoughts on future versioning/identification techniques and other such miscellaneous information.
Other Notes
In addition to the above conventions the following points should be considered when creating the documentation
Validation
When writing the documentation you should always refer to the GA release of the pattern to verify anything.
Where possible try to describe exactly what is going on in the pattern, for example if a pattern checks a specific variable then mention the condition it checks and the result of it evaluating to true or false.
Tables
Tables should follow a common format.
Categories
Categories should be added at the bottom of the page for a number of different value:
Publisher
The Publisher of the product, if multiple products are encapsulated within a single pattern or if multiple publishers are availible for the product then all of them should be listed.
e.g.
IBM]
Category
The Category the product falls into, found at the top of the page in the infobox.
e.g.
TKN Notes
A static TKN Notes value that indicates that the Wiki is part of a TKN Notes release.
Specific TKN Notes
A TKN Notes value that indicates the release that the Wiki is part of.
e.g.
Active Command Use
A static value that indicates if an Active Command or getFile command is used in the pattern.
Active Versioning
A static value that indicates if an Active Command or getFile command is used in the pattern to get Version information.
This should be used in conjunction with the Active Command category.
Path Versioning
A static value that indicates if a Path regex is used in the pattern to get Version information.
Registry Versioning
A static value that indicates if Registry querying is used in the pattern to get Version information.
Package Versioning
A static value that indicates if Package querying is used in the pattern to get Version information.