XP Meta-Documentation approach 
Author Message
 XP Meta-Documentation approach

Mark Roberts published here he is working on a documentation scheme.

Quote:
> Toward this end, I agree that it's important to come up with a plan that
> sketches out longer-range goals.

Taking inspiration from XP and other sources, I suggest we become "the
client" as a community and start a discussion about goals, structure and
functionality of such a framework.  So, all those wishing to contribute with
actual documentation have a pattern they can follow.

To get started, I would suggest the commenting areas in the various browsers
have hypertext capabilities.  This way, people can expand from very specific
explanations to more general ones, or side interests, or vice versa.

Another suggestion.  Many projects have the requirement to include all kind
of legalistic info with every class and method developed.  Some put that
info at the beginning of the code.  I would suggest, in those cases, to have
no more than one line: "Please, see legal information at the end of the
method".  This is because for developers it's a waste of time to have to
scroll through such stuff every time they need to understand how the code
works.  Another option would be to have an hyperlink: "Legal Information".
This way, the info is accessible, but doesn't appear as unnecessary text in
the body of the method.

Victor



Sun, 12 Jun 2005 00:16:43 GMT  
 XP Meta-Documentation approach
I would like to see a framework where such documentation is handled as
method annotations separate to and not within the actual method body source.
This could easily be handled via the class AnnotatedMethod in VisualWorks
including file-out/in with extended XML method source, not sure of other
dialects. In turn, with tool/browser support the actual format, content &
hyperlink capability could be made very flexible and the visibility of such
documentation could be controlled via browser preferences or navigation.

Thoughts and comments welcome.

regards Denis


Quote:
> Mark Roberts published here he is working on a documentation scheme.

> > Toward this end, I agree that it's important to come up with a plan that
> > sketches out longer-range goals.

> Taking inspiration from XP and other sources, I suggest we become "the
> client" as a community and start a discussion about goals, structure and
> functionality of such a framework.  So, all those wishing to contribute
with
> actual documentation have a pattern they can follow.

> To get started, I would suggest the commenting areas in the various
browsers
> have hypertext capabilities.  This way, people can expand from very
specific
> explanations to more general ones, or side interests, or vice versa.

> Another suggestion.  Many projects have the requirement to include all
kind
> of legalistic info with every class and method developed.  Some put that
> info at the beginning of the code.  I would suggest, in those cases, to
have
> no more than one line: "Please, see legal information at the end of the
> method".  This is because for developers it's a waste of time to have to
> scroll through such stuff every time they need to understand how the code
> works.  Another option would be to have an hyperlink: "Legal Information".
> This way, the info is accessible, but doesn't appear as unnecessary text
in
> the body of the method.

> Victor



Sat, 18 Jun 2005 13:00:47 GMT  
 XP Meta-Documentation approach

Quote:
>I would like to see a framework where such documentation is handled as
>method annotations separate to and not within the actual method body source.

Yes, please. And then make the 'method annotation tab' an option so it
disappears in sane environments (one where there are no PHB's that require
method headers etcetera) ;-). (I don't believe in method comments at all. I
believe in refactoring).

Personally, I think that structured class comments are the most important
thing to have. And the hardest part here is to select a standard. I propose
that we (the customer community) take a vote between:
- Perl POD
- python STX
- ...
(if you don't know either, these are *simple* markup languages, both with
large existing toolsets, and I think that's the way to go). A possible list of
stories would then include:
- Extensions (add bits of structure so you can tag classes, methods, ...)
- Checker/editor (show all the uncommented classes in a project/package/...);
- Processor (spit out equivalent HTML/LaTeX/...);

--

GnuPG 1024D/E0989E8B 0016 F679 F38D 5946 4ECD  1986 F303 937F E098 9E8B
Cogito ergo evigilo



Sat, 18 Jun 2005 16:42:01 GMT  
 
 [ 3 post ] 

 Relevant Pages 

1. BlackBox Meta: accessing methods through Meta

2. meta-circular-meta-interpreters (long)

3. #\Meta #\Control #\Meta-Control etc.

4. XP vs documentation

5. Linguistic approaches to AI Linguistic Approaches to Artificial Intelligence

6. Linguistic approaches to AI Linguistic Approaches to Artificial Intelligence

7. To XP or not to XP?

8. XP Home vs XP Pro - switch ???

9. XP mean Windows XP proffessional

10. Windows XP 64-Bit Ed., XP Corporate Ed. with incl. SP1, and XP Slipstream Sp1 Corporate

11. BUG: text <Meta-f> and <Meta-d> bindings in tk8.0a2

12. Wanted: small meta-data language

 

 
Powered by phpBB® Forum Software