|
Yeah sure, I've had that kind of documentation too.
I still got the calls.
When I left the company they just went through the code and all was clear.
The documentation was just decoration 
|
|
|
|
|
Do you remember what you were thinking when you wrote every piece of code?
I don't... so I write the documentation mainly for me. To be able to dig in my own mind some years later.
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.
|
|
|
|
|
Nelek wrote: Do you remember what you were thinking when you wrote every piece of code?
Lots of stuff, "I could really use a nap right now", "is it 5 'o clock yet?", "what movie am I going to see this weekend?", "I should buy a boat" that kind of stuff 
|
|
|
|
|
Sander Rossel wrote: I've written plenty of documentation, spent hours on it, only to end up with some document that no one ever reads again.
Well, I have to say, then, that you should have made it more useful/usable.
I've written millions upon millions of words of documentation, and customers love it, because it means that they don't have to stress out, trying to figure out how to do the things they want to do.
Which is kinda the point: you have to write documentation that tells stories, showing people how to use your product as part of a process that they already carry out, and demonstrating that your product makes that process less painful. The best documents are 2/3 use-cases.
Listings of what menu items do, what classes/interfaces comprise, or what the tools on a toolbar do (which is what all too many developers think of as being documentation), are completely useless to the end-user.
Stick that stuff in a Help file, and then write a document that tells users which menu items and buttons they have to select and press in order to complete a task that they perform.
Sander Rossel wrote: overall people just don't RTFM
Mark Wallace corrected: overall people just don't RFUD*
* Read Fruggin' Useless Documents
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Really, I know how to write.
I've a master in Journalism! 
My users (and coworkers) simply do not want to read. Ever.
At one time the IT manager of a customer even asked for a help button in some form. We spent a lot of time on it, describing exactly what each button did.
We made this big glaring "?" button on the screen that opened some external document and told him and the users about it.
After a few weeks I got an email from the same guy who asked for the help button "what does [some button] do?"
I literally copied it from the explanation under the "?" button (which took me 3 seconds) and he thanked me for my quick and clear answer
Then there's this customer who wanted a new application.
My manager wrote a change request, she supposedly read it and she did approve it.
After I wrote the application I wrote a step by step document describing how it worked (complete with screenshots and all).
Then I got a call "Hi Sander, can you please walk me through this application?"
"Yeah sure, but I've sent you that document..."
"I know, but I think it will be faster if we went through it together."
Again, I literally followed my own documentation and told her what was in it 
|
|
|
|
|
Been there, done that, got the t-shirt. The worst of it? It cuts on the will to write documentation altogether, and that's a slippery slippery slope.
* CALL APOGEE, SAY AARDWOLF
* GCS 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--- ++>+++ y+++* Weapons extension: ma- k++ F+2 X
* Never pay more than 20 bucks for a computer game.
* I'm a puny punmaker.
|
|
|
|
|
No it isn't, just don't write documentation 
It was hard for me to write, so it should be hard for my customers to use! :evil laugh:
|
|
|
|
|
MWAHAHAHAHAHAHAHAHAHAHAHAHAH
* CALL APOGEE, SAY AARDWOLF
* GCS 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--- ++>+++ y+++* Weapons extension: ma- k++ F+2 X
* Never pay more than 20 bucks for a computer game.
* I'm a puny punmaker.
|
|
|
|
|
Sander Rossel wrote: There are some exceptions, but overall people just don't RTFM.
A bit cynical eh? Those exceptions are what makes it worth it...besides, you only really hear from the ones who can't or won't try to solve it for themselves.
As for code documentation, that's another thing altogether, and one that I agree with you about...only the bare minimum required...use descriptive names and it should read like a book. 
"Go forth into the source" - Neal Morse
|
|
|
|
|
kmoorevs wrote: A bit cynical eh?
I'm just being realistic
|
|
|
|
|
Gives a new meaning to RTFM!
#SupportHeForShe
Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson
You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
|
|
|
|
|
The event will see the revelation of major information about exoplanets, or planets that orbit stars other than our sun, according to a release. It made no further mention of the details of what would be revealed. ET, white courtesy telephone please
|
|
|
|
|
They found God.
Not that they would ever admit that as they like being god.
NASA - Never A Straight Answer.
|
|
|
|
|
I was in the midst of my formative years at the time of the Challenger disaster and now, some 29 years later still think of the expansion of the acronym we cruelly joked about.
Need Another Seven Astronauts.
If you've not seen it, Prof Brian Greene does an excellent video on string theory, M-theory and the implications. M-THEORY & STRING THEORY (Explained) - YouTube
Of particular interest was the assertion that if given enough energy, a string can expand to a limitless size and can even form a surface or membrane, oft referred to as a brane. The "Big Bang" is postulated as being a result of the collision of two such branes - our universe resides on one of them and we are said to never have the ability to directly observe any others - though we may observe signs of their influence.
PBS Space Time is another fascinating youtube channel. The concepts and mathematics alone are enough to make a grown man weep.
|
|
|
|
|
enhzflep wrote: Need Another Seven Astronauts.
Amongst others as in one of the astronauts had 2 blue eyes - one blew this way...
enhzflep wrote: Prof Brian Greene does an excellent video on string theory
I recall reading the book some years ago. Fascinating stuff.
|
|
|
|
|
Ron Anders wrote: NASA - Never A Straight Answer.
|
Which is a sign of a good scientist. After all, no scientific theory can be proven, only disproven.
|
|
|
|
|
"Rogue One: A Star Wars Story" isn’t just a tale of scrappy rebels fighting against an evil Empire. With the issues it raises, including device authentication, asset management, and privilege control, it’s also a story about information security. Well, more like a cautionary tale. Always encrypt the plans for your Death Star
|
|
|
|
|
And the lesson to be learned here is: Don't encourage bad writers to make nonsense movies by paying to watch them.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Researchers have uncovered an advanced malware-based operation that siphoned more than 600 gigabytes from about 70 targets in a broad range of industries, including critical infrastructure, news media, and scientific research. "I know not with what weapons World War III will be fought, but World War IV will be fought with sticks and stones."
|
|
|
|
|
I have no idea how you connected that quote to this article, but now I have another reason to unplug my microphone 
|
|
|
|
|
Yeah, sometimes I type without a clue. I think it was implying that WWIII would be fought on the cyber.
Gotta stop Rum Mondays, I guess.
TTFN - Kent
|
|
|
|
|
He who steals my random ramblings steals trash.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
The rise of cloud computing has made enterprise software more accessible than ever before, but the quality of code and its ability to streamline daily business operations still falls short. Next report: Rise of 'low-code' development gives rise to need for more developers to fix 'low-code' solutions
EDIT - Sorry, looks like they pulled this article.
modified 21-Feb-17 13:23pm.
|
|
|
|
|
When three physicists first discovered through their calculations that a decaying atom moving through the vacuum experiences a friction-like force, they were highly suspicious. You mean all my under-graduate physics problems were lies?
modified 20-Feb-17 18:02pm.
|
|
|
|
|
Link Fail.
What do you get when you cross a joke with a rhetorical question?
The metaphorical solid rear-end expulsions have impacted the metaphorical motorized bladed rotating air movement mechanism.
Do questions with multiple question marks annoy you???
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
