On Thu, 1 Nov 2012, Hadubard wrote:

To: support@drupal.org From: Hadubard hadubard@gmail.com Subject: [support] Approaches to project documentation

Hi all,

I have to create a complete documentation of a rather huge Drupal based web project. My first idea has been to use the API module to use in-code comments to create an easy way to step through the code. I really like this in the drupal API documentation. But I also require a more general approach to fill the gaps between distinct parts in code in order to provide a general overview of how the pieces of the project are tight together, what assumptions and general ideas the project is based on, flow charts, etc ... I thought about using the doxygen @ingroup tag for that too (to create topics pages if I understand correctly), but my client argued that the use of accompanying images (flow charts, database schemas, etc ...) would be too difficult to include using this approach. What I really like about it is the possibility to have all the doc in our VCS.

I would be interested to hear about your approaches regarding this kind of project documentation. If you have any interesting resources or websites covering this topic I would be glad for a hint too. My search didn't yield very specific approaches but rather a general "yes, document what you do". But I'm more interested in a more or less detailed real life approach:

• What software do you use?
• How do you create cross references between code doc and general doc?
• Where do you store the doc?

Some links you might like:

http://en.wikipedia.org/wiki/PhpDocumentor

http://en.wikipedia.org/wiki/ArgoUML

http://alexdp.free.fr/violetumleditor/page.php

http://en.wikipedia.org/wiki/FreeMind

http://www.abisource.com/

HTH

Keith

----------------------------------------------------------- Websites: http://www.karsites.net http://www.php-debuggers.net http://www.raised-from-the-dead.org.uk

All email addresses are challenge-response protected with TMDA [http://tmda.net] -----------------------------------------------------------

Maybe http://drupal.org/project/drupaldocs can help? I get a lot of other hits when I search for document at drupal.org/project/modules.

On Thu, Nov 1, 2012 at 2:41 PM, Hadubard hadubard@gmail.com wrote:

Hi all,

I have to create a complete documentation of a rather huge Drupal based web project. My first idea has been to use the API module to use in-code comments to create an easy way to step through the code. I really like this in the drupal API documentation. But I also require a more general approach to fill the gaps between distinct parts in code in order to provide a general overview of how the pieces of the project are tight together, what assumptions and general ideas the project is based on, flow charts, etc ... I thought about using the doxygen @ingroup tag for that too (to create topics pages if I understand correctly), but my client argued that the use of accompanying images (flow charts, database schemas, etc ...) would be too difficult to include using this approach. What I really like about it is the possibility to have all the doc in our VCS.

I would be interested to hear about your approaches regarding this kind of project documentation. If you have any interesting resources or websites covering this topic I would be glad for a hint too. My search didn't yield very specific approaches but rather a general "yes, document what you do". But I'm more interested in a more or less detailed real life approach:

• What software do you use?
• How do you create cross references between code doc and general doc?
• Where do you store the doc?
• ...

best regards to all

[ Drupal support list | http://lists.drupal.org/ ]