Overview
Technical documentation created by development is intended to provide knowledge transfer from our department out to the rest of the organization. It can be used as the source for user guides as well as the source of truth on how features/functions are intended to behave. It provides the final implementation from requirement inputs and the basic usability, installation, configuration, integration, and troubleshooting. These documents will be a living document and should be maintained by the entire organization to provide the best value. If something is unclear or a new condition is discovered, everyone should update the document to provide team input and continuous improvement.
Basic Structure
There are four levels of organization possible in BoldWiki. These are Shelves > Books > Chapters > Pages. Below is some guidelines on how to use this structure as it relates to technical documentation.
Shelves
Individual Product Shelves – Every Distinct Product Line will have its own shelf. This should follow how we market/brand BoldGroup to the outside world. (Proposed change)
Books
Individual Product Category Books - If a product can be broken down into multiple categories, each will have its own book. (Move existing content)
Examples:
Manitou > MediaGateway
Manitou > ASAP-to-PSAP
AlarmBiller > SalesAutomation
AlarmBiller > eForms
Chapters
Product Feature Chapters - Each large feature should have a chapter to break the product down to navigable chunks. (Proposed change)
Examples:
Manitou > Manitou Web Client > SSO
AlarmBiller > SalesAutomation > Item/Parts Grouping
Pages
Feature Technical Details Page - For consistency we want to have pages for each of the following main documentation needs. Other pages may be optionally added as needed for additional clarity. (Proposed)
- Overview
- Technical Information / Usage
- Installation
- Configuration
- Integration
- Troubleshooting
Examples:
Manitou > Manitou Web Client > SSO > Overview
AlarmBiller > SalesAutomation > Item/Parts Grouping > Design Goal
Page Templates
Overview
A high-level snapshot for the reader to get a basic understanding of the scope of the project
- Design Goal
- Limitations
- Requirements
- Implementation
Technical Information / Usage
In-depth technical requirements and system specs required before beginning the implementation of the new product. Technical Information about the new product, overhead, expectations.
System Requirements – if the information is the same as other released products, the general system requirements can be in a separate page with a hyperlink added referencing the page. This way there is a single document to update if system requirements across all the referenced product features change. If the system requirements are specific to Product Feature, then the detailed requirements should be in a separate page of the product feature.
Supported Platforms – browsers, operating systems, etc. If the product feature has similar supported platforms to that of other product features, a single page can be created with the supported platform details and then a hyperlink referencing the general document can be added to product feature pages in which the general document is applicable. If a product feature has specific supported platform requirements, then a specific supported platforms should be created.
Dependencies – Examples: Outlook, Third Party Software, ios, etc. If the product feature requires the use of internal or external products, these dependencies should be defined with information as to the supported versions.
Some projects system requirements may differ from a broader project. But I’m sure we can just set up links where applicable to a general type system requirements doc. I was thinking along the lines of version info on one component that is part of the same system as well. Such as you can’t have the 3.0 VCC unless you are on 2.1.25 or above. Or PBX without a certain Aeonix version, etc… It might be very specific to the project. Some versions of *certain* things might run on an older OS and some may not.
Usage/Work procedure – (New Product)
- Instructions on how to use the project after they’ve installed it.
- Include screenshots of the project in action.
Installation
- Step-by-step instructions of how to install the new product feature. Any SQL queries, any installers, any files that require registration, etcetera.
- User rights – ie. Requires administrator rights
- License information
- Required Ports / IT changes
Configuration
- Step-by-step instructions of how to configure the new feature after installation.
- Prerequisites – data that needs to be predefined to streamline the installation process; such as user roles, user groups, form templates, setup preferences, data structure (gl accounts, customer/vendor # scheme, etc), default values, tax structure, etc.
- Passwords & access information
- Environment Variables
- SQL Server Configuration – ie. Protocols: TCP/IP, Named Pipes…
Integration
- Step-by-step instructions on how to integrate new product features into existing products and how to have a new product communicate with existing.
- Version requirements between the applications for this specific feature
Troubleshooting
- Possible errors that may come up and how to find and troubleshoot the cause and resolve.
- External References:
- Links to Third Party websites
- Other related wiki or web documents/articles
- Available resources for personal & professional development – ie. Links to applicable BoldU training, videos, etc
