[pmwiki-users] Wiki SSI to include a Program File

[Benjamin Wilson]

I believe I have dealt with your exact problem. I managed a small 
development team and we needed web-accessible documentation. However, we 
wanted to ensure the documentation kept current with the code. There's a 
thing called the DRY principle (Don't Repeat Yourself).

The first thing is it would be great _if_ you could write 
self-documenting code. That is, code that intuitively tells the reader 
what is happening. However, that is not always effective.

Perl uses a type of markup called POD (Plain Old Documentation). POD is 
a very brief form of text markup that can be included in the body of 
your code that can later be converted into HTML, RTF, or even PDF.

I required that every method used in my team's developing accompany a 
POD-annotated description that included the method's interface. If you 
are using any language that allows multi-line comments (e.g. PHP), then 
you can use POD. This allowed me to create a searchable web site where 
each program file had its own page.

However, we did not implement a way of presenting the code inline with 
the POD.

We also included project level documentation in POD as well. So, for 
example, we had a DBI interface that was fairly intricate. We never 
wrote a stitch of SQL in our program, sending it to the DBI interface 
that would turn the data structures into SQL. (Okay, some of the more 
complex WHERE clauses had to be spelled out.) To keep it organized and 
modular, we kept the DBI calls in a half-dozen different files--one for 
user interface, another for a different interface. These files were in 
their own directory (named 'dbi', naturally). In that directory, we had 
an overview POD file that explained how the DBI worked, how to call it, 
design concepts (i.e., why we did it in such a crazy way). The goal was 
that if the entire team died on the way to lunch, a new team could go 
and read the HTML documentation and pick up quickly.

This way, developers who were changing code in that directory had the 
documentation there, too, and could quickly update it. All this was 
stored in CVS as well.

So, I don't know if you need a wiki for this.

Ben



Sivakatirswami wrote:
> I would like to use PMWiki for documentation, but not duplicated  
> program code, which could change.
> 
> I'm sure this is an ancient "problem" and solutions have already been  
> worked out -- a philosophical search for the best way to manage  
> software development and documentation:
> 
> OK, a concrete scenario envisioned...  has
> 
> Page A on PMwiki details a series of processes. Or a completed  
> functional specification where some body of the code that implements  
> that plan has already been written and is in use.
> 
> _among them are references to a CGI (s and other "live" programs on a  
> web server) in the ./cgi-bin which is one level up from the docroot  
> where pmwiki lives and is being served.
> 
> -- I would like to be able to make some kind of link that would  
> dynamically pull in that code from that CGI for viewing the wiki,
> Page B we see the code but
>   a) the code cannot be tampered with directly.
> b) if the person in charge of that CGI (or any program for that  matter) 
> makes a change, the next time you go to the wiki and click on  the above 
> link you will see the same CGI but with its' updates...  this is kind of 
> like an SSI inside a non-editable wiki page or  section of a page.
> 
> I think you get the idea... responses to this could also suggest  other 
> strategies for the achieving the same goal. I find RCS a good  model, 
> for programmers who are actually modifying the code, checkin,  checkout, 
> checkin with comment.... But it requires cmd line check  savvy and a 
> terminal session if you want to review comments.
> 
> The bigger issue is: the program code is completely disconnected from  
> the larger body of documentation surrounding the project, of which a  
> small program or CGI is only a part.  Sometimes "documentation" is  more 
> properly placed as comments in the code itself, duplicating this  
> documentation in another context means two instances of the same data  = 
> headache...
> 
> if I go in and work on a major upgrade to the CGI, where comments are  
> critical for all to understand what it does...I would then have to  
> duplicate this explanation outside in the documentation. But then it  
> become unintelligible without the code itself forcing you copy the  
> entire CGI to the wiki... but then if you edit the CGI...  go back  and 
> update the docs...  you get the picture. There's got to be an  easier way.
> 
> Thanks
> Sivakatirswami
> 
> 
> 
> 
> 
> _______________________________________________
> pmwiki-users mailing list
> pmwiki-users at pmichaud.com
> http://host.pmichaud.com/mailman/listinfo/pmwiki-users
> 
> 
> 
>