Creating useful Technical Documentation for a project
-
The most important thing is to : 1. give just the amount of information the (receiving) person needs. 2. provide a way for the person to get more information when the information from #1 leads them into thinking about deeper issues. But, how do you do this? I believe that is where (a few) UML diagrams come in. It has taken me years to understand this, but I'll try to explain. A good example to start out with is the Use Case Diagram which is often considered (especially by developers) as so abstract that it might even be useless. However, the use case diagram shows three important things: 1. scope 2. high level view of functionality the system provides 3. system boundary With a proper Use Case Diagram you can immediately get a feel for how large (scope) the project is and an idea of what it does. You also see a boundary and other systems (actors) which may use the system. People at higher levels (Project Manager, Sales) may never need more than the Use Case Diagram. They just want to know what the system does. That diagram _should_ lead the viewer to ask more questions. I wish there were a way to include images here. Suppose we have a Use Case diagram like the following: ATM example[^] A customer can make a deposit. How does that work? Now, you are going to want to create a flow of some sort. This will be an behavioral diagram which shows how things work. [ Customer clicks Start button] [ Customer selects Deposit choice] [ Customer chooses type of deposit (cash or check) ] You'll use the activity diagram something like the following: Activity diagram[^] Now, more details are beginning to become apparent. But, the developer wants to know what the structures in your program look like. For example, is there a deposit object? Now you need a Class diagram (structural document). After that, the developer wants to know how the Deposit object interacts with the Account object to store and update the amount that is in the Account. For that, you'll show more detail in a Sequence
Sounds like that would make life way to easy for the next dev ;P When I worked in the support department at a previous company I had to fix code that I usually had no idea of how it worked because it was written by the dev team and then just passed on to support. I just had to start by looking at the code and debugging. Although it sucked it did teach me good debugging and problem solving skills.
-
Yeah, this is probably the best option overall for getting something useful out. I'd still like to use a tool to generate some of the flows and diagrams though, it's a pretty big project.
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
-
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
-
Sounds like that would make life way to easy for the next dev ;P When I worked in the support department at a previous company I had to fix code that I usually had no idea of how it worked because it was written by the dev team and then just passed on to support. I just had to start by looking at the code and debugging. Although it sucked it did teach me good debugging and problem solving skills.
I have a particular activity diagram for a specific service (in prod) which shows each flow and possible errors. The software we use (Enterprise Architect[^]) allows me to generate an image of my diagrams and I've posted it to the Intranet. (NOTE: the tool is fantastic and you can get it for a very reasonable price -- but the learning curve is huge -- extremely overhelming at times.) My support team can get an error code back, look it up on the activity diagram and know exactly where in the code the failure occurred and know how to resolve it. It actually saves me so much time and it creates more of a team atmosphere since everyone can actually see exactly what is going on in the code.
-
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?
Wow. When I'm leaving a job I delete comments and rename variables.
-
Wow. When I'm leaving a job I delete comments and rename variables.
F-ES Sitecore wrote:
When I'm leaving a job I delete comments and rename variables.
You may actually be doing everyone a service. Speaking for myself, I know my comments are often outdated with regards to what the code is now doing (that part is more true than humor), and obfuscating variable names is a motivation to work out the code without trusting the programmer named them well and spelled them correctly (again, sadly less humor and more true for code I've had to work with that others wrote.) 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'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?
There is already a bunch of good advise in the comments. It also becomes obvious that relevant documentation should be kept up to date as good as possible. What if you just leave or create a heap of lorem ipsum stuff? Is anybody gonna review the documents you produce? How likely is it that the next person will just create his own set of documentation and don't even look at what you created? From your question I get also the impression that there isn't any expectation regarding the deliverable from your managers side.
-
There is already a bunch of good advise in the comments. It also becomes obvious that relevant documentation should be kept up to date as good as possible. What if you just leave or create a heap of lorem ipsum stuff? Is anybody gonna review the documents you produce? How likely is it that the next person will just create his own set of documentation and don't even look at what you created? From your question I get also the impression that there isn't any expectation regarding the deliverable from your managers side.
-
The documentation will definitely be used. I'll have some training sessions with the person taking over the project as well. Just sometimes difficult to get concepts over onto paper.
That's good to hear that there will be somebody looking at it! Will you do the documentation with your successor together if possible? By that he can already make himself familiar and provide feedback in a very early stage.
-
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?
Start with a description, in plain English, of the problem you are trying to solve. Next, explain, in plain English, your thinking process in arriving at your chosen solution and outline the pros and cons of that solution. In other words, give the next person an insight into your thinking process.
-
That's good to hear that there will be somebody looking at it! Will you do the documentation with your successor together if possible? By that he can already make himself familiar and provide feedback in a very early stage.
-
Wow. When I'm leaving a job I delete comments and rename variables.
When I was at the University, one of my fellow students did his hand-in exercizes the other way around (or, I guess it is opposite of your renaming): While writing program code, his integer variables were named I01, I02, ..., float variables F01, F02 etc. He would never wast the line space and typing effort of using those long, descriptive names demanded by the professor. The last edit before handing in the assignment was to replace I01 with NumberOfApplesInEachCrate and F02 with AverageWeightOfEachApple, and so on. I am not defending his work style, but can't help being impressed by his mental capacity to developp and comprehend quite complex software without the aid of descriptive names. (My first programming language was BASIC, in those days when it REALLY was basic... Variable names one letter, or one letter and one digit. Programs exceeding 100 lines were big ones. Under those conditions, you can manage without descriptive variable names.)
-
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?
Like jgrogan, above, I am not Politically Correct - I think plain English has a definite place in the documentation, as opposed to machine generated, strictly formalized and structured documentation. The latter has its definite place as a dictionary of details for future maintenance, but not to make your follower understand your code. I draw a line between that which is independent of your implementation tools and the implementation details. Think of the first part as something that won't be changed at all if your system is re-implemented in a different language, one with different mechnamisms. Not that you will switch to another language, but it helps you keep the irrelevant details out of (that part of) the documentation, and focus on the essentials. It will be fairly stable: You can do a lot of code changes without the algorithms, data structures, functional modularization etc. being changed. Maybe new functions are added and data structures extended, but that rarely has any large impact on the old parts. The dividing line between implementation independent and dependent details may of course be discussed. E.g, I assume that an algorithmic language will be used for implementation, so I can describe flow using pseudocode that won't be useful if someone would implement the solutionin a predicate language (like Prolog). Given an algorithmic implementation, it is irrelevant whether the language provides foreach or repeat-until, dictionary structures etc, if short and long values are provided or not, if there is a distinction between count values (i.e. integers) and measurement values (i.e. float/real) - the implemnetation independen doc will reflect whether a value is a count or a measurement (or whatever) at a semantic level, but not as "data type". When writing code comments and using automatic documentation tools for the formalized, directoroy style information, you can leave out descriptions of module and data structures, algorithms etc, assume that is known from general part, and focus on the implementation details. OK, some (maybe most) methodologies pretend to take such an approach, but they succeed only partially. E.g. information modelling is often done in a way that assumes specific mechanisms, limitations etc; essentially as programming objects with a simplified syntax. E.g. you decide at a design level whether a list of names is a name array or a List - even if the decision is not absolute, the tools strongly favors specific implementations. So I dislike most rigid technolo
-
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.
