Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Possible Duplicate:
Methodology for Documenting Existing Code Base

What is the best format/setup for an architecture document? That is, the document that comes out of brainstorming an idea and then finding a technical process in which it will be made. There really isn't much details at this point, just a logical flow of how things will work. Flowcharts are good, I guess, but at certain times, I find that the boxes need a paragraph to explain.

A lot of people have told me about Doxygen, but that's more for documenting code itself (which I will have to do at some point on an existing application).

share|improve this question
    
What kind of information, exactly, are you trying to capture? There's a lot of different information that might go into an architectural design document. It depends on who the target audience of the document is, what kind of application you are building, and so on. –  Thomas Owens Aug 8 '11 at 1:07
    
@Thomas - mostly design choices, overview of the classes, the major methods in them, the inheritence levels, etc. This document would be produced by the tech lead, possible in conjunction with other tech leads, (or possibly their development manager) and then this can be given to a senior programmer, who can start to build it. –  M.R. Aug 8 '11 at 1:59
    
@George I don't think this is a duplicate. The question you linked to is more about documenting the code itself via comments whereas this one is about documenting the overall structure of the application. –  Anna Lear Aug 8 '11 at 3:18
add comment

marked as duplicate by George Stocker, Walter, ChrisF Aug 9 '11 at 10:00

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

1 Answer

I have found it useful to create this type of documentation using org-mode in emacs. Now that babel has been included in the main releases you can actually execute code inside your documentation and it makes for an ideal technical documentation generator. Your org-mode docs can then be exported to whatever format you need. The combination of literate programming, plus information management, Gantt charting with taskjuggler, and finally the export to pdf, html, or whatever else you can dream up is pretty hard to beat.

That said, you need to be (or want to be) an emacs guy and some feel these tools have steep learning curves but once you learn 'em you'll love 'em.

As a final note since it's all just text when you're using emacs you can check the docs into the repo. Everyone who has something to add regarding the classes, the interfaces, etc. can do so easily with their favorite text editors at their convenience. Always good to do docs like this using the lowest common denominator so you can pull in everyone.

share|improve this answer
add comment

Not the answer you're looking for? Browse other questions tagged or ask your own question.