What makes a good developer / system documentation?

Posted by deamon on Programmers See other posts from Programmers or by deamon
Published on 2011-03-15T17:04:38Z Indexed on 2011/03/16 0:18 UTC
Read the original article Hit count: 373

Filed under:

documentation

Much time is wasted to get new developers started with existing software systems, because there is no good documenation. But what makes a system documentation good? One thing is a good API documentation like the Java API doc, but how to transfer the "bigger picture" and other things that cannot be placed in the API doc?

One constraint is that it should not be to hard and time consuming to write the docs, because that is one reason why it is omitted so often.

So, what makes documentation good?

Related posts about documentation

Hyperlinked, externalized source code documentation

as seen on Programmers - Search for 'Programmers'
Why do we still embed natural language descriptions of source code (i.e., the reason why a line of code was written) within the source code, rather than as a separate document? Given the expansive real-estate afforded to modern development environments (high-resolution monitors, dual-monitors, etc… >>> More
A tool to aid completion of missing or incomplete source code documentation

as seen on Stack Overflow - Search for 'Stack Overflow'
I have several finished, older PHP projects with a lot of includes that I would like to document in javadoc/phpDocumentor style. While working through each file manually and being forced to do a code review alongside the documenting would be the best thing, I am, simply out of time constraints,… >>> More
Quick C# Project Documentation in Visual Studio

as seen on Internet.com - Search for 'Internet.com'
Here's a quick way to document your .NET projects. >>> More
SQLAuthority News – Feature Pack for Microsoft SQL Server 2005 SP4

as seen on SQL Authority - Search for 'SQL Authority'
If you are still using SQL Server 2005 – I suggest that you consider migrating to later version of the SQL Server 2008/2008 R2. Due to any reason, you wanted to continue using SQL Server 2005, I suggest that you take a look at the Feature Pack for Microsoft SQL Server 2005 SP4. There are many… >>> More
SQLAuthority News – Statistics Used by the Query Optimizer in Microsoft SQL Server 2008 – Microsoft Whitepaper

as seen on SQL Authority - Search for 'SQL Authority'
I recently presented session on Statistics and Best Practices in Virtual Tech Days on Nov 22, 2010. The sessions was very popular and I got many questions right after the sessions. The number question I had received was where everybody can get the further information. I am very much happy that my… >>> More

Developer IT