|
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.
|
|
|
|
|
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<names> - even if the decision is not absolute, the tools strongly favors specific implementations. So I dislike most rigid technologies and their tools - they restrict my freedom in designing solutions.
Jacquers' task is not to choose a design tool for a new project; neverhteless I think it is relevant to approach his documentation task as if his system was designed this way, with a distinct separation between the solution at conceptual level and the way it is implemented.
|
|
|
|
|
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" 
|
|
|
|
|
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.
|
|
|
|
|
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!
|
|
|
|
|
|
Visio (Pro) can do all the diagrams listed; and then some. You can also combine, link, publish, etc.
"(I) am amazed to see myself here rather than there ... now rather than then".
― Blaise Pascal
|
|
|
|
|
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
|
|
|
|
|
|
DocFX for documentation, WebSequenceDiagrams for your diagramming needs, bingo bango (which means you're already almost done)!
|
|
|
|
|
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.
|
|
|
|
|
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.
|
|
|
|
|
Can an icy cell hold the Pope's letter? (9)
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
Encyclical? but that's 10 letters and needs another 'c' from somewhere.
Otherwise an anagram of an icy cell.
Andy B
|
|
|
|
|
I miscounted - it's supposed to be an anagram of "Can icy cell" with the "an" thrown in to mislead and make a sentence.
But it's the right answer. Do you want it tomorrow, or should I be punished with doing another? Your choice.
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
I'll do it tomorrow
|
|
|
|
|
I hope you can count better than I can ... 
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
AntiTwitter: @DalekDave is now a follower!
modified 8-Jun-17 6:36am.
|
|
|
|
|
You of all people - pulling me up on Teresa May
We can’t stop here, this is bat country - Hunter S Thompson RIP
|
|
|
|
|
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
More like Dianne Abbott 
modified 8-Jun-17 9:31am.
|
|
|
|
|
Sounds naughty, doesn't it?
Anyway, does anyone use Amazon to sell their stuff? Pros/cons?
I used to use Digital River a long time ago, and now forget why I stopped.
I'm currently doing the whole PayPal IPN thing set up with MojoPortal, and it works...but...PayPal.
Any other services out there that are worth looking at? I just need a click-the-link-on-my-site-to-pay, the buyer goes and pays someone else, then either returns to me for the download (like the IPN thing), or downloads from the same place they paid (like Digital River).
|
|
|
|
|
I am currently searching the internet for info on Face Recognition Software.
Unsurprisingly, the SEO jungle makes this about as efficient as doing college research papers back before the internet ever existed.
If you know what you're talking about with Face Recognition Software, please contribute to this thread (or send me a private message).
As for this immediate moment, my goals, agenda, and requirements are (purposely) not sharply defined. I just want to get a sense of what's out there, and how the various segments of the software work; particularly how they interface with other parts of a given system (e.g., a database, or whatever)
The jargon, vocabulary, nomenclature, and general lingo used in the trade are on my list of things to learn.
If there's a better place here on CodeProject to ask this question, point me.
|
|
|
|
|
I recall Pete O'Hanlon was doing face recognition work for a local museum if I am not wrong. He might be able to help.
"It is easy to decipher extraterrestrial signals after deciphering Javascript and VB6 themselves.", ISanti[ ^]
|
|
|
|
|
That's correct. I have done a fair bit around this already.
This space for rent
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
