Re: How to document algorithms?
Could anyone point to a source on documenting algorithms for software
development? Is there a specific industry standard? Does it have to
include UML flow charts or a plain text description would suffice?
An algorithm, which may be a subroutine of a complex system or may be the whole system, is traditionally documented with standard flowcharting symbols. These symbols include sheet connectors so that you can work at a legible scale on reasonable paper sizes and continue the logical flow on succeeding pages. However, if you are publishing online rather than on paper, you can make your pages quite large to avoid a lot of fragmentation.
With large systems, it is customary to show a subroutine as a single block, with a reference to the sheet where its logic is detailed.
When all is said and done, though, merely documenting algorithms is not sufficient to fully characterize a large system. You also have to document data structures (database tables) and the flow of data between program modules and the database. The latter is done with data flow diagrams, which Tony believes he's not allowed to mention here but which are a necessary component of complete documentation.
With both flowcharts and data flow diagrams, it is helpful to visualize a system as a tree structure, with the whole system as the top node, the data structure, the data flow, and the logic as the three nodes immediately below the top, and more finely granular structures extending down from each of them.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today!. http://www.webworks.com/techwr-l
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com
To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.
How to document algorithms?: From: Viorel Lupu
Search our Technical Writing Archives & Magazine