Solved

Code Documentation Requirements

Posted on 2006-11-06
3
166 Views
Last Modified: 2010-04-16
Dear Experts:

I have a group of coders who are currently working on development of a large web based application.  I would like my group of programmers to document the application they are coding in such a way that in addition to commenting their code, they produce a document that would be of asssistance to other coders in the fututre that will be working on modifying and customizing the application.  In a sense, a document that will be used to navigate the code base of the application.

Is there any methodologies that could be followed to produce such a document?  If I were to list out requrirements for the document, what should I specify?
0
Comment
Question by:superfly18
[X]
Welcome to Experts Exchange

Add your voice to the tech community where 5M+ people just like you are talking about what matters.

  • Help others & share knowledge
  • Earn cash & points
  • Learn & ask questions
3 Comments
 
LVL 19

Accepted Solution

by:
VoteyDisciple earned 125 total points
ID: 17881326
I don't think this directly answers your question, but I'm a big fan of the kinda-make-believe "phpdoc" syntax if you're using PHP.  Basically this works just like Javadoc where class and method documentation can be automatically pulled out to make a handy webpage.  I've seen a number of tools to do this with PHP as well (Google will be as good at recommending one in particular as I, however).

That's not to say you wouldn't want a Systems Manual or other similar out-of-code documents, but I've found just having the aggregated documentation for the code pulled out and easy to browse goes a long way toward being able to understand a system.


By now I wouldn't be surprised if similar tools existed for other web languages as well.  I know .NET has its own XML syntax for doing this, for instance.
0
 
LVL 24

Expert Comment

by:SunBow
ID: 17883057
Step one is what are requirements. For example, you begin with files and fields with some constraints. The output is likely intended for a specific audience, has anyone bothered to ask them what they think product should look like (not do).

Chart how thing flow from one stage to another. From one system to another. Jot note about conversions done, directions and changes in direction.
0
 
LVL 1

Author Comment

by:superfly18
ID: 17883382
This happens to be a JSP development project.  There actually is a detailed specification put together.  Despite how things are specied, their actual implementation may mainifest itself in many different forms.  The real question here is that, say in five years someone is asked to develop a customization to the application, or modify it, perhaps significantly, and the original development team is not available.  What would the breadth of the documentation include that the new development team would like to see to be able to understand and navigagate the code base.  
0

Featured Post

Technology Partners: We Want Your Opinion!

We value your feedback.

Take our survey and automatically be enter to win anyone of the following:
Yeti Cooler, Amazon eGift Card, and Movie eGift Card!

Question has a verified solution.

If you are experiencing a similar issue, please ask a related question

This article will show, step by step, how to integrate R code into a R Sweave document
Computer science students often experience many of the same frustrations when going through their engineering courses. This article presents seven tips I found useful when completing a bachelors and masters degree in computing which I believe may he…
Viewers will learn how to properly install Eclipse with the necessary JDK, and will take a look at an introductory Java program. Download Eclipse installation zip file: Extract files from zip file: Download and install JDK 8: Open Eclipse and …
Simple Linear Regression

707 members asked questions and received personalized solutions in the past 7 days.

Join the community of 500,000 technology professionals and ask your questions.

Join & Ask a Question