• Status: Solved
  • Priority: Medium
  • Security: Public
  • Views: 173
  • Last Modified:

Code Documentation Requirements

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?
1 Solution
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.
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.
superfly18Author Commented:
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.  
Question has a verified solution.

Are you are experiencing a similar issue? Get a personalized answer when you ask a related question.

Have a better answer? Share it in a comment.

Join & Write a Comment

Featured Post

Free Tool: Path Explorer

An intuitive utility to help find the CSS path to UI elements on a webpage. These paths are used frequently in a variety of front-end development and QA automation tasks.

One of a set of tools we're offering as a way of saying thank you for being a part of the community.

Tackle projects and never again get stuck behind a technical roadblock.
Join Now