TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: How to document algorithms? From:Tony Markos <ajmarkos -at- yahoo -dot- com> To:Viorel Lupu <pidgin -at- ua -dot- fm>, techwr-l -at- lists -dot- techwr-l -dot- com Date:Fri, 5 May 2006 05:31:48 -0700 (PDT)
--- Viorel Lupu <pidgin -at- ua -dot- fm> wrote:
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?
Tony Markos responds:
There are no industry standards. Here are some time
tested rules of thumb:
* If there is alot of decision branching, then
graphics are necessary - at least to properly plan
your text.
* Can potentially many things happen at the same time?
Logical flow charts (if-then-goto flow charts) are
not meant to handle this, and text is a particuarly
poor tool in such situations.
* If you do logical flow charting, can you fit the
flow chart on about one 8 1/2" by 11" piece of paper?
Logical flow charts are primarily meant to document
small systems.
* For larger-scale systems documentation efforts, Use
Case have a tragic flaw: They fail to prod the analyst
through a rigorous requirements elicitation. For
larger efforts this is often fatal.
* For large systems with complex decision branching
and potentialy many things happening at the same time,
there is only one way to go - use of an analysis
technique mention of which is taboo on this listserv.
If you need to know about such situations, go to the
requirements engineering listserv where solutions to
such problems are openly discussed.
__________________________________________________
Do You Yahoo!?
Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
