Search code examples
documentationservicerequirementsinteraction

How to organize information about program solution?


Неllо. I develop system that works with stock exchange(system, below). And there is a lot of information my program need to interact with this system. This system has formal declared interface, but different details beside this declaration and requirements to my system is often changed. So how can I organize available information about this system and requirements to my program that it could be both easy to understand and easy to change.


Solution

  • Your first and foremost goal is to create documentation for the relevant APIs your program exposes and then add documentation for the configuration files, maybe even set up a validator for configuration that.

    Automatically generated content from code annotations (depending on your solution, it might be .NET's XML docs or PHPdoc, etc.) is the first step – this will help you document classes and interfaces as you work on the code. The next step is documenting non-code assets. If you have XML configuration, you can write schemas to validate against, for example.

    After that comes integration documentation – steps that need to be taken on the production server and/or workstations to install, upgrade and maintain the application, including support scripts.