THE BUSINESS ISSUEA vital step in distributing knowledge of an information system is formalizing technical documentation.
For technical document to be genuinely usable, it must meet the following criteria: - Users must know the documentation is entirely up to date,
- It must be quickly and easily accessible,
- Documentation must synthesize information, and
- Users must be able to easily search for desired information.
There is no advantage in producing documentation just to say it exists. However, this is often what organizations end up doing, so documents are quite often obsolete.
THE ARCAD SOLUTION
The goal of ARCAD-Observer is to automate the process of producing documentation as much as possible. After analyzing all the criteria listed above, we quickly concluded that HTML is the best documentation format. This format really does simplify information distribution. Any user can access it via the Intranet and be certain they are working in the right version. Users can perform searches at their workstations using traditional search engines. 
ARCAD-Observer generates your documents in HTML format. All diagrams are inserted as pictures or as executables if you wish to provide navigation functions directly in the generated pages. For example, this is how the organization diagrams produced by source code analyzer are displayed.
You can also easily define hypertext links to all kinds of external documents. As an example, you can link to any kind of existing documentation. How does it work?
The product allows definition of a variety of standards (technical documentation, user documentation, operating folders, and version folders) which are called models. These models can be configured in terms of chapters and sub-chapters.
You select parameters (entire application, functional sub-branches, modified components, etc.) and apply a model to obtain the needed documentation. The documentation editor lets you round out automatically generated sub-sections with functional information formatted as notes. The editor can also incorporate all diagrams generated by Observer – including screen shots or hard copies – into your documentation. Observer produces documents in HTML by automatically managing documents’ table of contents, format, and graphical design. It is then easy to put them on an Intranet to facilitate information sharing. Updating Documentation
For documentation to be usable, it must be entirely up to date, so we have included update mechanisms. Our list merger system ensures that existing documentation is shared, and that the component description is updated. Automatically generated sections can be automatically replaced, while preserving customized sections. Of course, manually inserted diagrams can be refreshed as well. |
