Home > Archive > Software Engineering > September 2007 > looking for ideas for code documentation
You are viewing an archived Text-only version of the thread.
To view this thread in it's original format and/or if you want to reply to
this thread please [click here]
| Author |
looking for ideas for code documentation
|
|
| Woland99 2007-09-23, 4:26 am |
| Howdy,
I am trying to find some tools to facilitate writing design/overview
documents
describing a proprietary language source. The language is used for
modeling
real life situation and typical development tasks consist of writing
either completely
new logic or using/extending current structures to model new parts/
behaviours.
It would be helpful to have documentation that would be an overview of
certain
typical tasks (modeling new part - properties and behaviours), flow of
logic, relevant
class attributes or methods etc - that would written as eg. Word file
with frequent links
to source code. My question is mostly about maintaining those links -
since code
constantly evolves and language does not support access restriction so
anybody on
the team can modify any file at any time. So if I write a doc and it
refers to some
specific method and somebody makes modification to that method I would
like to
know about it so I can possibly update the documentation. Likewise
person that
modifies/enhances the code should be warned that there is certain
documentation
dependent on that code.
I am looking for sth fairly lightweight - not Literate Programming
type - maybe as
simple as sth to maintain some image of code tagged with unique tags
that can
be referenced in Word documents - and links to proper parts of the
source code.
Maybe with checksums for the methods/classes formed on preprocessed/
decompiled
code stored in parallel so if any area of the code that has a tag that
is part of any
documents is modified then we can alert developer and document author.
Thanks for any pointer/keywords/ideas.
JT
| |
| Mr. Workflow 2007-09-23, 7:10 pm |
| On Sun, 23 Sep 2007 06:22:32 -0000, Woland99 wrote:
> Thanks for any pointer/keywords/ideas.
Free, of course.
--
´Users don˙t know what they want. So XXXX 'em"
| |
|
| Woland99 wrote:
> I am trying to find some tools to facilitate writing design/overview
> documents
> describing a proprietary language source. The language is used for
> modeling
> real life situation and typical development tasks consist of writing
> either completely
> new logic or using/extending current structures to model new parts/
> behaviours.
Sounds like a job for literate acceptance tests, like http://fitnesse.org/
Not sure why you need Word if HTML is the most common markup format. I think
the FIT family has hooks for Word, too...
--
Phlip
|
|
|
|
|