|
honey the codewitch wrote: I find that creating a technical article not only makes it easier for people to get their feet under them using it (at least I think so), it also helps me later to flesh out an outline of the major components of the software, which then evolves into a table contents. Finally that becomes master documentation.
I agree 100%.
I'm always interested in how to communicate technical details to an audience without confusing or boring them. What makes it better?
Mostly, I mean shorter when I say better.
After reading numerous brain books I discovered something that is interesting.
Almost everything you know & think about has been learned through Context.
The easiest example here is you need to remember a list of 15 things.
If you simply attempt to remember them you will get 5 +/- 2.
However, if you build a story around those 15 things it is quite likely you will remember them. Humans need context.
And so it is with documentation (IMO). A lot of documentation is simply a list of technical details.
However, if you provide Context -- think of communicating how the thing works as if it is a story to a listener who is somewhat interested.
This does generally mean documentation is longer but if you do it right it will be so much better it will seem shorter (in most cases).
|
|
|
|
|
If you're talking about documentation similar to Mozilla's and Spring's then I'm 100% on board 
|
|
|
|
|
IMHO it depends very much what you describe in '///' If it is only the list of parameters then it would be useless.
I saw a lot of such documentations for APIs... but the list of parameters I see allready in the code.
|
|
|
|
|
I created "leveled" Data Flow Diagrams (DFD's) for all the financials of Company XXX which were turned over when everything was outsourced. In effect, you're reverse engineering. Code comments won't do it if you expect someone else to get a higher understanding of how things work; which is usually what's needed first / most. With a high level view, it's easier to decide at what point to stop with the details.
"Before entering on an understanding, I have meditated for a long time, and have foreseen what might happen. It is not genius which reveals to me suddenly, secretly, what I have to say or to do in a circumstance unexpected by other people; it is reflection, it is meditation." - Napoleon I
|
|
|
|
|
I'm using Sandcastle Help File Builder myself, which generates documentation from comments in code.
It also allows to add custom content using the "MAML" language, but that has a steep learning curve.
Here are some other options: documentation-tools-for-net-developers[^]
|
|
|
|
|
Documentation of "what" (such as that generated by Doxygen) is happening is not always that useful. I find an explanation of "why" is much more helpful. Unfortunately there is no tool that can do that for you.
- I would love to change the world, but they won’t give me the source code.
|
|
|
|
|
Best documentation I see explains "Why?" Ask why the code exists, and sometimes for why the design was used vs other alternatives. The level of explanation depends on the complexity of the project.
|
|
|
|
|
The why often depends on how something fits into the bigger picture. The rationale can be anything from architectural to it had to be done this way to mesh with some PoS that we didn't have the time to rewrite. These things would usually be described in a the HLD, but the discipline to make those living documents is rare.
|
|
|
|
|
I'm in the situation now where I have to take over an array of projects without any help from the original programmer.
Here's what I want to know: HOW DO I RUN THIS STUFF LOCALLY!?
Any configuration I need to know about?
Also, how do I deploy!?
Do I have to copy some files, run database scripts, do a VS deploy, run a pipeline?
When "the business" talks about an application, what Git repositories do I need?
Also, are there any projects that should be changed together, which is not obvious from the code (for example, because they share a database dependency).
I'm rarely interested in documentation about the code.
I can read the code.
I can click a button/call an endpoint and set a breakpoint to follow through the code.
The things I want to know are the things I can't know without knowing (this sounds more profound than I had meant it to be  ).
|
|
|
|
|
That I have documented for the most part on one of the projects so far 
We're putting some effort into documenting a lot of our processes and info now. Previously it had been in emails, some documents, etc. but now it's getting combined into Confluence. Finally... now that I'm leaving
modified 14-Apr-22 1:00am.
|
|
|
|
|
Pretentious: Good code doesn't need documenting, it is self explanatory.
Reality: I am lazy
In practice, I try to minimize in-code documentation to reduce clutter and limit it to "magic" code, where I have used an unconventional technique that might confuse a lesser mortal.
Nothing succeeds like a budgie without teeth.
To err is human, to arr is pirate.
|
|
|
|
|
absolutely agree. Suffering with this right now.
Charlie Gilley
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
Has never been more appropriate.
|
|
|
|
|
I think it's more your "experience" knowledge that will be useful for the next person - so I would argue that a document explaining the domain knowledge and why certain APIs and code work they way they do may be of far more use than code documentation.
I say this because I spend a lot of time reading code and the most useful information I get from other developers is information like "yeah, this is what can go wrong and this is how the customer uses the API".
“That which can be asserted without evidence, can be dismissed without evidence.”
― Christopher Hitchens
|
|
|
|
|
You asked for advice and are getting a whole range from a diverse set of viewpoints!
I will say that some of the most important things to document are:
1) Dependencies/Build/install/setup
2) Validation. How do you test/validate (or who else is responsible). Built in Testing?
3) Deployment Guidelines
4) Risks, Previous issues, and the most problematic code
5) The overall architecture, and a "Metaphor" for how to view the system
6) Any indication of how they might locate something (or the logic of the structure choosen)
Look at it this way. Assume YOU were walking in on day 1. The new developer to replace the previous.
You have NO CLUE what this system does. How to build it or test it. If you are even using the latest source.
Your confidence is in the toilet, and they need you to get up to speed.
What type of information would increase your confidence, and get you able to BUILD and VALIDATE the build the quickest?
Then what information would allow you to NAVIGATE the code logically?
Finally, assuming you only fixed a Typo... On your first day. What would make you feel okay to publish that change???
Document those things. NOT the code, per se.
IMHO
|
|
|
|
|
Sometimes the best coding dramas are written in the comments. (aside from some funny jokes)
But sometimes a good laugh is the best way to make people remember the oddities of certain hacks or unusual algorithms.
If I ever see Windows ME's source code, I'd expect to see shitfaced comments all over the people (evidence of Balmer's Peak)
|
|
|
|
|
Comments are often restricted to what the code does, this is only half the story. It arguably more useful to know why its been written or why it's been written a particular way, this can't always be inferred from the code itself.
|
|
|
|
|
Not sure if I brought up this topic before.
As I have aged, I am starting to develop Arthritis in my fingers, particularly my mouse clicking finger.
Does anybody know of a good speech to text program that can be used to control development in Visual Studio?
Are any of you suffering from the same issue?
Nutcracker Sweet
|
|
|
|
|
Slow Eddie wrote: Are any of you suffering from the same issue?
yes, I am.
I plan on going to the doctor and seeing what they can do for me, or if they have suggestions, such as alternative mouse devices, etc.
I have tried voice/speech programs, in the past, for other reasons than this topic, and it is not how I would want to code, etc.
|
|
|
|
|
|
@OriginalGriff uses trackballs, maybe he can help with suggestions for ergonomic mouse alternatives?
GCS/GE d--(d) s-/+ a C+++ U+++ P-- L+@ E-- W+++ N+ o+ K- w+++ O? M-- V? PS+ PE Y+ PGP t+ 5? X R+++ tv-- b+(+++) DI+++ D++ G e++ h--- r+++ y+++* Weapons extension: ma- k++ F+2 X
|
|
|
|
|
Yeah I've been getting steadily worse in finger and knees, not overweight just a lot of wear and tear.
The less you need, the more you have.
Even a blind squirrel gets a nut...occasionally.
JaxCoder.com
|
|
|
|
|
Yes, I use trackballs, but they probably wouldn't help with the mouse click finger as that's the same on on mine.
Though I remember one Logitech trackie that used the thumb instead: Trackman Marble FX[^] - that might be worth looking at, since you can work both the ball and buttons with your thumb if you need to.
Personally, I didn't get on with it - too slow for Doom - but others swore by them.
I've yet to meet a TtS that worked well enough to be more help than harm, even for text documents - for dev? Try producing code on a tablet screen keyboard and you'll get the idea how bad it is.
There are eye tracking mice though - for example Precision Gaze Mouse[^] not sure how you click those though.
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
OriginalGriff wrote: not sure how you click those though.
You have to cross your eyes to click! 
The difficult we do right away...
...the impossible takes slightly longer.
|
|
|
|
|
And extropic for a double click? 
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
Thanks I will give both a try. I have tried all of the trackball mice, and the cursor moves much to slowly for me, even when I set the windows mouse parameters to full speed
ed
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
