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.

We are a small team of 5 developers and I'm looking for some great advices about how to document the software architecture and design. I'm going for the sweet spot, where the time invested pays off. I don't want to use more time documenting than necessary.

I'll quickly give you my thoughts.

What are the diagrams I should made? I'm thinking an overall diagram showing the various applications and services. And then some sequence diagrams showing the most important or complicated processes.

About the code it self, I really don't see much value in describing or making diagrams for the code outside the .cs files them self.

About text documents, I'm a bit uncertain about when to put down on paper. Most developers don't like to either write or read long documents.

share

migration rejected from stackoverflow.com Oct 23 '13 at 18:42

This question came from our site for professional and enthusiast programmers. Votes, comments, and answers are locked due to the question being closed here, but it may be eligible for editing and reopening on the site where it originated.

closed as too broad by gnat, MichaelT, Kilian Foth, World Engineer Oct 23 '13 at 18:42

There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs.If this question can be reworded to fit the rules in the help center, please edit the question.

3  
Do not document it. Make it clear to understand. That should be enough. –  Arnis L. Mar 11 '11 at 10:56
9  
^ You surely have never worked on a large scale project, or maybe even a medium one –  Imran Omar Bukhsh Mar 11 '11 at 12:52
1  
The simple answer to this question is that you document anything the team had to figure out. Anything that you cannot simply look at and understand, even that stuff, should be documented. In 5 years all 5 of you might be gone, the project might be 24 people strong, and they want to know the reason your design was choosen. –  Ramhound Mar 11 '11 at 16:50
comments disabled on deleted / locked posts

5 Answers

What are the diagrams I should made? I'm thinking an overall diagram showing the various applications and services.

UML Component Diagram and Deployment diagrams for this are essential.

We use Argo UML. The price is right. It works well.

And then some sequence diagrams showing the most important or complicated processes.

Only if there is a proven need; i.e., someone asks for it.

About text documents, I'm a bit uncertain about when to put down on paper. Most developers don't like to either write or read long documents.

False. Developers don't like to read rambling, unfocused documents that lack concrete code examples. Hints: Focus. Code.

Another hint.

Avoid fancy desktop word-processing tools. Documentation -- like code -- should be plain text and checked into your code repository.

We use Python-based Sphinx and docutils. The documentation is written in RST (ReStructuredText) markup. Simple tools create HTML pages or LaTeX (and later PDF) from the simple RST source. Diagrams are exported as PNG's so that they're easily processed by other tools.

Since the documentation is plain text, it's easy to write, easy to edit, easy to copy and paste and (above all) under source code control along with everything else.

Another Hint.

To the extent possible, build documentation from the code.

Sphinx can pull comment blocks from the code. Since we use Python, it's trivial to produce a complete, good-looking and well-organized document from the code plus extra RST files.

The "extra" files are the use case overviews (for which no code can possibly convey the information), the architectural overviews, plus management overheads like the backlog, operational guide, administrative notes, etc.

share
    
what is your team size which is presently following this? –  Aditya P Mar 11 '11 at 13:20
    
I wish I could vote again. –  Erin Mar 11 '11 at 13:32
    
@AdityaGameProgrammer: about a dozen. Most of them prefer the PDF's, which are produced from LaTeX by a simple set of tools. Others use the HTML. Some use the original RST files. –  S.Lott Mar 11 '11 at 13:40
1  
+1, though I disagree about argouml. Yes, it is free, but it is also out of data with regards to UML. I found it difficult to work with and the biggest deal breaker is lack of undo functionality; don't make any mistakes with delete if you use that. –  jmq Mar 11 '11 at 13:52
    
I would like to mention plantUML. While it might not be very intuitive compared to argoUML, it is very nice to have the UML diagrams in plain text as well (to put them under source code control, too). –  Tobias Heinicke Jul 8 '13 at 11:10
add comment

I propose you use java-doc like comments in the code, whatever fits your language, e.g. JavaDoc, Doxygen, Sandcastle, jGrouseDoc...

UML tools like "Enterprise Architect" can generate class diagrams from your source code, and allow to to draw other diagrams relatively easily. Those tools are not prohibitively expensive anymore.

share
add comment

I have good experience with a Wiki. A Wiki is lightweight and it is simple to modify on changes to keep it actual. A good idea is a structure like described in arc42. If impossible to setup a wiki, simple HTML pages in a filesystem with a HTML editor would do it for small projects.

But you are right, less is more here! Describe few, more an overlook with the aims and thoughts than details. And keep it up to date - that is hard enough with with a small number of pages, many teams failed starting with a large documentation which is useless after a year of development.

Some UML diagrams of components and sequences are very useful. You can simply create them on a whiteboard and take a photo to upload it into the wiki or use a tool to draw them (very simple and cool: plantUML).

Generated documentation like class diagrams from code are not useful from my opinion because they tend to become to detailed and will mostly miss any explanations. Some diagrams with the core classes should be more stable and can be documented better to understand the architecture.

share
add comment

A good entry level solution for documentation/architecture is Enterprise Architect by Sparx Systems. It is not free, but it is not crazy expensive either.

I personally like to use Sybase PowerDesigner, but it is very expensive.

share
add comment

If you're interested in documenting how your class/classes work you could do a lot worse than use the Sandcastle Help File Builder.

*You simply need to enable XML Comments in whatever language you're building your application in, then when you compile you will see a myapplication.xml file that the shfb tool can use to build a .CHM file.

*Assuming of course you're using Visual Studio

share
    
Not a valid link any more =( –  CodeBlend Jan 30 '13 at 10:34
add comment

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