|
|
Posted by Rik on 12/17/06 04:10
Peter Fox wrote:
> My opinion is this:
> * You need pre-coding documentation
> * You need in-code documentation (During development this will include
> tags to loose ends such as '[T]' for deserves a test routine, '[D]'
> for 'needs to be mentioned in the user documentation'. For this you
> need commenting standards and a program to interpret the standards.
> * You need an object/routine/method/property summariser which scans
> code to produce nitty-gritty documentation such as what sort of
> parameters are required and whet the result will be...
> * ... but you also need functional grouping of objects/methods to be
> able to quickly navigate 'by feel' through code.
> * IMPORTANTLY you need _briefing documentation_ that gives the
> background to all sorts of matters inherent in your code or assumed by
> the environment. For example how would someone twiddling with your
> code (it could be you in a couple of years time!) access the
> database? Using an object, set of objects, hierarchy of objects and
> what would be the basic set-ups for those objects? Two ways are used
> here:- 1 - Comments and exercise code in the main code
> 2 - Stand alone example exerciser code.
> I prefer method 2 as it is easier to split 'what it should do' from
> 'how it works'.
>
> All-in-all (even though I have a very visual style of learning) I
> would rather spend the time others spend on pretty pictures, doing
> written documentation and exercise code.
>
> Put yourself in the position of a USER of a mass of code. An overview
> diagram and outline of the principles behind the relationships would
> be very useful - ie. where objects fit in the overall plan ... ...
> but then you need to know what each object is about *in specific
> detail* and *quickly*.
Putting myself on the the position of a user I want both: A comprehensive
diagram of overall flow, and a user guide which explains all possibilities
in detail. An overall overview really helps understanding, 'a picture is
worth more then a thousand words' still applies.
Offcourse, it all depends on how much of the flow the users should be aware
about to use it. It's one off those rare occasions in miss M$ however. M$
Visio was apt to my need, but I'm not going to pay for it. It's the free
graphic programs I use now to clear up certain dependancies, but they're
not very user-friendly.
--
Rik Wasmus
Navigation:
[Reply to this message]
|