Creating useful Technical Documentation for a project
-
Jacquers wrote:
Any suggestions for tools to use?
Your brain. Seriously. Specialized tools are limiting. Document: * your design decisions * the problem(s) your code solves * the problem(s) your code created * 3rd party / service / whatever dependencies If it's complicated code: * a high level architecture diagram can be useful, but class diagrams are sort of not. Instead, diagram the interaction between objects is probably more useful * workflows are better than classic flowcharts, which can be too low level. Who needs to actually see triangles for "if" statements? Visio (or similar), Word (or write in HTML or markdown). Create a table of contents! Why not specialized tools? Because those often have a steep(er) learning curve, and maintaining something with a specialized tool is sort of a mental blocker for people. The ability to take a drawing or a text/wiki/etc. annotate it with notes (particularly as the new guy learns things and wants to make notes) is soooo much more useful. Marc
Latest Article - Create a Dockerized Python Fiddle Web App Learning to code with python is like learning to swim with those little arm floaties. It gives you undeserved confidence and will eventually drown you. - DangerBunny Artificial intelligence is the only remedy for natural stupidity. - CDP1802
Excellent advice. What's more, by the time you have learned a specialized tool, will there still be time to do the job?
-
Jacquers wrote:
Any suggestions for tools to use?
Your brain. Seriously. Specialized tools are limiting. Document: * your design decisions * the problem(s) your code solves * the problem(s) your code created * 3rd party / service / whatever dependencies If it's complicated code: * a high level architecture diagram can be useful, but class diagrams are sort of not. Instead, diagram the interaction between objects is probably more useful * workflows are better than classic flowcharts, which can be too low level. Who needs to actually see triangles for "if" statements? Visio (or similar), Word (or write in HTML or markdown). Create a table of contents! Why not specialized tools? Because those often have a steep(er) learning curve, and maintaining something with a specialized tool is sort of a mental blocker for people. The ability to take a drawing or a text/wiki/etc. annotate it with notes (particularly as the new guy learns things and wants to make notes) is soooo much more useful. Marc
Latest Article - Create a Dockerized Python Fiddle Web App Learning to code with python is like learning to swim with those little arm floaties. It gives you undeserved confidence and will eventually drown you. - DangerBunny Artificial intelligence is the only remedy for natural stupidity. - CDP1802
I echo Marc's comments and will add that an over arching objective of good documentation of this type needs to be based on what the objectives are of the process and then how those objectives are achieved (in code or process). So often, I have seen where massive investments over time have been lost and replaced by lesser effective delivery systems simply due to the fact that the person or persons that assumed the support of those processes was ill-informed of the full story of 'why' this process is as it is and as a result assumes that there are serious gaps that must be corrected or the entire process replaced. In a high number of these situations, at some point later there is a realization that the legacy process was sufficient and perhaps covered gaps which the replacement process creates. Thereby creating a cycle of waste.
-
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've done quite a lot of this type of documentation in the past - my advice to you in your situation with the limited time you have is to create high level diagrams explaining how things are put together (as you have already done). Also document build and deploy procedures. I've used Visio for this in the past - but in my current job I've been using Lucidchart [^] and I would highly recommend that if you are not already a Visio "pro" :)
-
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?
Lots of good ideas here, but depending on your situation, preferences and comfort level you could consider offering a different approach: - Make an outline (mental or otherwise) of all the information you want to convey. - Set up meeting(s) with the staff who will take over your projects. - Present the material. - THEY create the documentation. - You can give the documentation a once over afterwards if you are inclined. In addition to saving you the agony of writing documentation, the company gets the benefit of having remaining staff become familiar with your projects before you are out the door.
-
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?
Don't forget to document the environment. Have they Imaged the development machine, is it a VM so they boot and go. Can they even install all of the components and compile it. Next up: 80/20 rule. 80% of the changes are caused by 20% of the system. Think in terms of a few recent requested changes... Next up: do you have a bug tracker tied to version control? If so, I would consider adding contextual information to the old bugs to make clarifications. I would RATHER you have them: 1) Know how to build/deploy the system 2) Know how to use Source Control/Bug tracker to learn from (so they keep using them BOTH) 3) Know if they have a potential issue: Document the NEVERS that many don't document... 4) The Coding Standards and Guidelines so they continue with Code Reviews! After that, I think you can assume a professional can generate class diagrams on their own, with the tools they like (I don't usually bother), and they can spend the requisite time seeing the types of code changes made, and what requests were tied to them. In stable systems it will be change requests. In new systems, it is usually bug fixes, or story implementation... HTH!
-
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?
As a part of a bigger enterprise I am using Confluence - Team Collaboration Software | Atlassian[^] with Plant UML macro that is capable of different type of diagrams (activity, use case, sequence, class and more). It is true that with first few examples you might need to study a bit the documentation (but it is out there) and I am not sure how does the licensing work (I saw there is trail version but haven't tried it). Apart of these, sometimes I reach for these tools too: Flowchart Maker & Online Diagram Software[^] XMind: The Most Popular Mind Mapping Software on The Planet.[^] WWW SQL Designer[^] I hope it helps
-
Jacquers wrote:
I'd still like to use a tool to generate some of the flows and diagrams though, it's a pretty big project.
Point taken -- I do occasionally find it useful to have Visual Studio create a class diagram (there are better tools for that though than VS) and even more helpful is having SQL Server (or whatever) create a diagram of the schema. Then again, if you're using NoSQL... :~ I think the most difficult thing to do is documenting the lay of the land. Too high level, and it's useless, too low level, and a new person gets overwhelmed. Though we all despise PowerPoint, a slide deck that is a guided tour of the project, where you can isolate and show code/schema areas (not the actual code necessarily) along side the UI/services/business logic, MVC patterns, etc) that they are responsible for can be really useful, with drill-downs for critical stuff, especially the stuff you would label as "do not touch unless you know what you're doing." This works particularly well if your code base is nice and modular. Discussion of where tests are, whether they are automated, unit tests, manual, how you've tested the software, is also really helpful as a starting point. Marc
Latest Article - Create a Dockerized Python Fiddle Web App Learning to code with python is like learning to swim with those little arm floaties. It gives you undeserved confidence and will eventually drown you. - DangerBunny Artificial intelligence is the only remedy for natural stupidity. - CDP1802
+1 on what I think Marc's saying. It's less important to document how the application is working. Developers can read your code and figure that out. What I call "philosophical documentation" is at least as important. Why did you design an aspect the way you did, why does the API take these parameters, what does each layer represent and examples of the type of work which should be in that layer, etc, etc. Nobody else thinks like you do. They may not be able to get in your head from the code base. Let them in there to know how you were thinking about the problem(s). All of that said, I applaud your effort to think of the next wave.
-
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.