Doc-O-Matic White Paper. Copyright (c) 2002 by toolsfactory Inc. All rights reserved.

Transcription

1 Doc-O-Matic White Paper Copyright (c) 2002 by toolsfactory Inc. All rights reserved.

2 Doc-O-Matic White Paper Page I Content Why Documenting 1 Documenting Well 2 Source Code Documentation with Doc-O-Matic 2 User Documentation and Printable Manuals 4 Index 5 Version:1.0 Page I

3 Doc-O-Matic White Paper Page 1..:: Why Documenting Software is becoming more and more complex. That's why documenting Source Code and explaining the functionality of software to the customer using a documentation is becoming increasingly important. For developers documenting their own source Code is very useful, if they have to use their own source code after a while for example to fix bugs or to make an update. Documentation will help them to remember quickly how their code is working. Source code documentation is even more useful for other developers. Developers have to understand how source code created by another developer works. For example if there occur bugs in a project caused by the interaction of pieces of software developed by different developers or if some parts of a software developed by different developers must be fit together. If the source code is properly documented this is a lot easier. For the manager of the project or the producer of the software source code documentation is absolutely necessary for the following reasons: The biggest advantage for the manager of the software project or the producer is that source code documentation saves time. It saves time if other developers have to understand code created by another developer. If source code is properly documented new employees can join an existing team needing far less training time and as a result far less training costs. Source code documentation can also be used to proof the specific performance of the agreed specifications of the software to the customer. Finally, sometimes the producer of the software has to document the source code because he is obliged to. But source code documentation is only as useful as described above if the software is not only documented but documented well. Version:1.0 Page 1

4 Doc-O-Matic White Paper Page 2 Criteria for well documented Source Code and Application Documentation are:..:: Documenting Well Good Documentation has to be uniform. If you first have to get used to how the documentation works you lose time. Good Documentation is clearly arranged so that you can easily understand the software. Good Documentation is sufficiently detailed. Good Documentation is always up-to-date. Good Documentation is complete. Good Documentation is always consistent. But creating the documentation must not need longer than it later helps you saving time. To make sure that your Source Code Documentation fulfills all these requirements you should use a Documentation tool. Doc-O-Matic has been created to help developers and technical writers develop documentation. Doc-O-Matic supports the producer of software to optain optimal results with perfectly documented software...:: Source Code Documentation with Doc-O-Matic By using Doc-O-Matic, source code documentation becomes simpler and time-saving and ensures that the source code is documented well: Version:1.0 Page 2

5 Doc-O-Matic White Paper Page 3 Doc-O-Matic parses source code written in C/C++ and Delphi natively and virtually any other programming language that supports comments. It provides the developer and the technical writer with a good basis for the documentation of the source code. Developers and technical writers do not have to analyse the Source Code themselves. This makes documenting the source code easier regardless of whether developers themselves or technical writers document the source code. Doc-O-Matic provides the person who documents the source code with a multi-purpose environment for documenting source code, which automatically formats the generated documentation. Doc-O-Matic generates HTML-help, HTML files, Windows-help and even PDF files. This is a tremendous advantage of Doc-O-Matic compared to it's competitors. Doc-O-Matic ensures that the documentation is always up-to-date and that it is consistent with the source code. By formatting the content of the documentation in a well structured way Doc-O-Matic ensures that the documentation is clearly arranged. Doc-O-Matic ensures that the documentation is complete by pointing out certain inconsistencies and missing documentation to the technical writer or the developer. If you prefer to use directly documented source code for internal documentation, Doc-O-Matic can put the documentation written with Doc-O-matic back into the source code, at the location prefered by the developer or technical writer. Using Doc-O-Matic you can not only write source code documentation but also application documentation. This has several additional advantages: Every kind of documentation of a company is looking uniform. Every kind of documentation is available in HTML-help, HTML files, Windows-Help and PDF. Documentation is time saving because the technical writers or the developer can use the same tool for the source code documentation and the user documentation. Version:1.0 Page 3

6 Doc-O-Matic White Paper Page 4..:: User Documentation and Printable Manuals By creating application documentation and a printable user manual, Doc-O-Matic helps you in many ways: Doc-O-Matic provides you with an environment that automatically formats the content of the documentation and comes with the most common word-processing tools. This includes automatic generation of indexes, tables of contents and references to both inside and outside of the documentation. You can modify these settings and format the application documentation uniformly however you like it. As Doc-O-Matic saves the settings separately from the content of the documentation you have the possibility to modify the settings while or after writing the documentation and you can alter the order of the different parts and the structure of the document. Doc-O-Matic creates HTML-help, HTML files, Windows-help as well as user manuals in the widespread and freely available PDF-format. The possibility to generate a user manual has several additional advantages: You don't have to make a user manual separately. The manual has exactly the same content as the application documentation. You don't have to use another software to create the manual. Version:1.0 Page 4

7 Doc-O-Matic White Paper Page 5 Index D Documenting Well 2 S Source Code Documentation with Doc-O-Matic 2 U User Documentation and Printable Manuals 4 W Why Documenting 1 Version:1.0 Page 5