Solved

Code Documentation Requirements

Posted on 2006-11-06
3
165 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

[Webinar] Code, Load, and Grow

Managing multiple websites, servers, applications, and security on a daily basis? Join us for a webinar on May 25th to learn how to simplify administration and management of virtual hosts for IT admins, create a secure environment, and deploy code more effectively and frequently.

Question has a verified solution.

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

Does the idea of dealing with bits scare or confuse you? Does it seem like a waste of time in an age where we all have terabytes of storage? If so, you're missing out on one of the core tools in every professional programmer's toolbox. Learn how to …
This is about my first experience with programming Arduino.
In this fourth video of the Xpdf series, we discuss and demonstrate the PDFinfo utility, which retrieves the contents of a PDF's Info Dictionary, as well as some other information, including the page count. We show how to isolate the page count in a…

737 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