[support] Approaches to project documentation

[Keith Roberts]

On Thu, 1 Nov 2012, Hadubard wrote:

> To: support at drupal.org
> From: Hadubard <hadubard at 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]
-----------------------------------------------------------