|
Quite possibly, in any case it's a bit disconcerting to me, to her not so much. We're very different in that respect.
"the debugger doesn't tell me anything because this code compiles just fine" - random QA comment
"Facebook is where you tell lies to your friends. Twitter is where you tell the truth to strangers." - chriselst
"I don't drink any more... then again, I don't drink any less." - Mike Mullikins uncle
|
|
|
|
|
My phone? A Flip Phone!
My "Smart TV" has no internet access.
I'm going to go back to changing my MAC address, when browsing, more frequently.
You can keep most of the control away from THEM . . . easy habits to develop.
Or you can walk around with a dumb grin, let them do what they want . . .easy habits to develop.
| Ravings en masse^ |
|---|
| "The difference between genius and stupidity is that genius has its limits." - Albert Einstein | | "If you are searching for perfection in others, then you seek disappointment. If you are seek perfection in yourself, then you will find failure." - Balboos HaGadol Mar 2010 |
|
|
|
|
|
Why is there so much software like this?
Why do people still create software like this?
How do these systems still get created and implemented?
ComputerWorld -- Now THAT'S what we call a rounding error! | Computerworld[^]
Here are the snippets from the article:
Quote: "We were originally told the managers would adjust our clock in/out times if we deviated from our schedule,
Quote: Say I clock out at 4:37 p.m. -- it's rounded to 4:30.
"However, if I clock out at 4:38, then I register as getting eight minutes of comp time. Only we're not allowed to earn comp time...
Quote: "Why did they decide against having the managers adjust our times? It's too much work. It seems it takes the managers about an hour to process each person's timesheet.
|
|
|
|
|
raddevus wrote: Why did they decide against having the managers adjust our times? It's too much work. It seems it takes the managers about an hour to process each person's timesheet
Huh? what does the software do then?
Sin tack
the any key okay
|
|
|
|
|
Lopatir wrote: what does the software do then?
Sits at the PC and plays Freecell.
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
Lopatir wrote: Huh? what does the software do then?
It saves time, of course.
Some people just don't get technology, I guess. 
You hit it right on with that one.
|
|
|
|
|
raddevus wrote: Why is there so much software like this?
Why do people still create software like this?
How do these systems still get created and implemented?
A few other things you could replace "software\systems" with:
Children.
Governments.
Politicians.
[fill in with further more soapbox-appropriate words]
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
|
|
|
|
|
Haha! Made me genuinely LOL!
~ G.B. Shaw When you find something funny, search it for the hidden truth!
|
|
|
|
|
And here I was thinking this was going to be about floating point precision numbers.
Not sure if this was better or worse, but it's quite funny and sad at the same time (Schrödinger's joke?) / 
|
|
|
|
|
I'll just be 5 minutes late in the morning and make up for it by leaving 5 minutes early... It zeroes out, right?
Director of Transmogrification Services
Shinobi of Query Language
Master of Yoda Conditional
|
|
|
|
|
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?
|
|
|
|
|
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
|
|
|
|
|
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.
|
|
|
|
|
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 diagram which shows (behavioral) interactions between the objects as functionality runs.
For this you want a sequence diagram:
sequence diagram[^]
A Key To Understanding Documentation
Keep in mind that each document really only explains things from one viewpoint.
Generally those viewpoints can be broken down into two categories:
1. behaviorial
2. structural
Each of these items allows the particular viewer to dig further and further into the amount of detail they need.
It's how it all adds up to actually present your ideas.
|
|
|
|
|
Sounds like that would make life way to easy for the next dev 
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.
|
|
|
|
|
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.
|
|
|
|
|
Excellent advice. What's more, by the time you have learned a specialized tool, will there still be time to do the job?
|
|
|
|
|
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.
|
|
|
|
|
In addition to the exceptional answer by Marc, as tool I can think of Latex too. My wife wrote Doctor-Thesis on it and results were way better than usual word files. But... it is a bit PITA until you get how to use it, I had to sit down myself and look for examples, try-error myself to get some stuff she wanted done.
Personally I used MS Visio a lot to make relational diagrams, workflows, structure graphics. Afterwards embedded it in Word (company wanted it so)
M.D.V. 
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
|
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.
|
|
|
|
|
Wow. When I'm leaving a job I delete comments and rename variables.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
