Creating useful Technical Documentation for a project
-
I agree with what's already been posted. Make sure you explain the *why* of your decisions instead of the *how*. Many developers will explain how something works but they leave out the reason that they chose that solution in the first place. For example: - Explain why you chose a commercial solution over an open-source solution (or vice-versa) - Explain any failed attempts at complicated code before arriving at the current solution - If it's not obvious, explain the problem you were trying to solve with certain pieces of code Chances are the next developer will be able to work through your code and understand *how* things work, but typically documentation is the only way to explain *why*.
Quote:
Chances are the next developer will be able to work through your code and understand how things work, but typically documentation is the only way to explain why.
This is a great point! Thoughtful and useful documentation is hard, which is why we're having this conversation. And we routinely focus our efforts in the wrong place when creating content.
-
I'm leaving my current employment at the end of July and I'm tasked with creating documentation for whoever has to maintain the project(s) that I have worked on. I have created some of my own documentation explaining how things work and fit together, but I'd like to create more than that. Most of my code has comments and so far I have tried several documentation tools, but I'm not too happy with the kind of documentation they produce. A list of classes and methods is maybe Ok for API documentation, but isn't really going to help someone get to grips with the project. I'd like to have some class diagrams and it would be really nice to have some UML diagrams or maybe even some flowcharts. For those of you that have done technical / developer documentation, how did you go about it? Any suggestions for tools to use?
-
I'm leaving my current employment at the end of July and I'm tasked with creating documentation for whoever has to maintain the project(s) that I have worked on. I have created some of my own documentation explaining how things work and fit together, but I'd like to create more than that. Most of my code has comments and so far I have tried several documentation tools, but I'm not too happy with the kind of documentation they produce. A list of classes and methods is maybe Ok for API documentation, but isn't really going to help someone get to grips with the project. I'd like to have some class diagrams and it would be really nice to have some UML diagrams or maybe even some flowcharts. For those of you that have done technical / developer documentation, how did you go about it? Any suggestions for tools to use?
My $0.02, I use Visio to document state diagrams (with a 1-1 correspondence between code and diagram in terms of states and transitions), and OneNote to document process of developing the code, leaving a trail of process and of how-to notes, documenting how to use a particular device etc. Atle
-
I'm leaving my current employment at the end of July and I'm tasked with creating documentation for whoever has to maintain the project(s) that I have worked on. I have created some of my own documentation explaining how things work and fit together, but I'd like to create more than that. Most of my code has comments and so far I have tried several documentation tools, but I'm not too happy with the kind of documentation they produce. A list of classes and methods is maybe Ok for API documentation, but isn't really going to help someone get to grips with the project. I'd like to have some class diagrams and it would be really nice to have some UML diagrams or maybe even some flowcharts. For those of you that have done technical / developer documentation, how did you go about it? Any suggestions for tools to use?
I use Database Documentation Reports - Home[^] to document the schema and or SQL Server diagrams. I use Sandcastle - Documentation Compiler for Managed Class Libraries - Home[^] to convert the internal VS XML comments into HTML help files and web-sites. Phil
-
I'm leaving my current employment at the end of July and I'm tasked with creating documentation for whoever has to maintain the project(s) that I have worked on. I have created some of my own documentation explaining how things work and fit together, but I'd like to create more than that. Most of my code has comments and so far I have tried several documentation tools, but I'm not too happy with the kind of documentation they produce. A list of classes and methods is maybe Ok for API documentation, but isn't really going to help someone get to grips with the project. I'd like to have some class diagrams and it would be really nice to have some UML diagrams or maybe even some flowcharts. For those of you that have done technical / developer documentation, how did you go about it? Any suggestions for tools to use?
[
DocFX
](http://dotnet.github.io/docfx/)for documentation, WebSequenceDiagrams for your diagramming needs, bingo bango (which means you're already almost done)!
-
I'm leaving my current employment at the end of July and I'm tasked with creating documentation for whoever has to maintain the project(s) that I have worked on. I have created some of my own documentation explaining how things work and fit together, but I'd like to create more than that. Most of my code has comments and so far I have tried several documentation tools, but I'm not too happy with the kind of documentation they produce. A list of classes and methods is maybe Ok for API documentation, but isn't really going to help someone get to grips with the project. I'd like to have some class diagrams and it would be really nice to have some UML diagrams or maybe even some flowcharts. For those of you that have done technical / developer documentation, how did you go about it? Any suggestions for tools to use?
You want to leave documentation? Just set the titles, copy-paste man pages for the contents. Nobody ever reads this junk anyway, we all know that the code (if there is a "the" code) is light years away from any existing docs. No, that's not what I did when I left, but I could have.
-
Wow. When I'm leaving a job I delete comments and rename variables.
F-ES Sitecore wrote:
Wow. When I'm leaving a job I delete comments and rename variables.
Surely, you jest ? The consequences of such an action, depending on your contractual agreement with your employer, and the legal system you are in, could be very serious.
«Beauty is in the eye of the beholder, and it may be necessary from time to time to give a stupid or misinformed beholder a black eye.» Miss Piggy
-
I'm leaving my current employment at the end of July and I'm tasked with creating documentation for whoever has to maintain the project(s) that I have worked on. I have created some of my own documentation explaining how things work and fit together, but I'd like to create more than that. Most of my code has comments and so far I have tried several documentation tools, but I'm not too happy with the kind of documentation they produce. A list of classes and methods is maybe Ok for API documentation, but isn't really going to help someone get to grips with the project. I'd like to have some class diagrams and it would be really nice to have some UML diagrams or maybe even some flowcharts. For those of you that have done technical / developer documentation, how did you go about it? Any suggestions for tools to use?
In addition to the usual architecture diagrams and documentation, I've taken to creating a small Knowledge Base (ours can be partitioned, so I create one for the particular project). Then I walk through and put all the common issues I've come across, or gotchas that I can think of in this Knowledge Base. Typically we start hand over a bit earlier than the cut-over date and any questions that the support team have, I can put these into the KB and then have the support team use that. Whatever it can't answer, I will and then update the KB for them. It can be time consuming but I think it helps greatly as people can simply 'google' the answer for a particular error or question about the system. It depends how nice you want to be to the people you are handing the project over to I suppose :) I also do this when I have been handed a system to support and have no supporting documentation. Creating a KB and putting new articles in any time I encounter a problem helps as I am forced to dive deeper into an issue and fully understand how it works.
-
F-ES Sitecore wrote:
Wow. When I'm leaving a job I delete comments and rename variables.
Surely, you jest ? The consequences of such an action, depending on your contractual agreement with your employer, and the legal system you are in, could be very serious.
«Beauty is in the eye of the beholder, and it may be necessary from time to time to give a stupid or misinformed beholder a black eye.» Miss Piggy
Yes, I jest. It's something we call a "joke", an anecdote that probably isn't true but told for amusement :)
-
F-ES Sitecore wrote:
Wow. When I'm leaving a job I delete comments and rename variables.
Surely, you jest ? The consequences of such an action, depending on your contractual agreement with your employer, and the legal system you are in, could be very serious.
«Beauty is in the eye of the beholder, and it may be necessary from time to time to give a stupid or misinformed beholder a black eye.» Miss Piggy
... and don't call him Shirley
-
You want to leave documentation? Just set the titles, copy-paste man pages for the contents. Nobody ever reads this junk anyway, we all know that the code (if there is a "the" code) is light years away from any existing docs. No, that's not what I did when I left, but I could have.
Reading between the lines I guess there was no time allocated for documentation during the dev cycle. You are now expected to rush out a full manual in the limited time you have left. Bottom line is that documentation takes time to produce, during which no revenue generating activity takes place. Equally, when the guy who wrote the code leaves the building, the business is in jeopardy. Usual reaction to this scenario is PANIC!!!!
We're philosophical about power outages here. A.C. come, A.C. go.