|
Kent Sharkey wrote: Shame about all those products Microsoft never created
Hey!
The help file for calc.exe is just about OK!
End of statement.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Documentation is either overrated by developers and their managers or underrated by customers.
I've written plenty of documentation, spent hours on it, only to end up with some document that no one ever reads again.
My customers call me when something is unclear, way faster than reading the docs.
I look it up in the code, which is way faster and more reliable, than looking it up in the docs.
What's worse, with a constantly changing system the docs change so quick that it's almost impossible to keep up with.
Writing the initial specs is easy, but updating them is a bitch since you need to find the parts that are outdated and replace them (that potentially means deleting documentation that you've written earlier, something a lot of people won't do!).
The documentation will soon be a potential amount of your "development" time.
And no one ever reads them.
Documentation is kind of like a code comment.
When you have to write it think to yourself "how can I change this so it doesn't need documentation?"
There are some exceptions, but overall people just don't RTFM. See, there's even an abbreviation for it!
One exception I make to this is API documentation for external systems.
You'd hate to download .NET, Node.js, AngularJS, even a small library, and not find ANY documentation whatsoever.
Luckily, my systems are rarely used by others (I'm not a fan of documenting) 
|
|
|
|
|
Sander Rossel wrote: My customers call me when something is unclear, way faster than reading the docs
But what if you've left the organisation, on annual leave or just unavailable? Also, when you're the "goto" guy for a problem, and no one else understands the system, then you're the one who will be bugged out of work hours and weekends. I've been there and worn that t-shirt. I document "everything" that I do. That way, there's no reason to bug me unless it's critical. So whilst documentation may take some time in the outset, it saves me a lot of stress and time in the long run. And keeping it up-to-date is just something I build into my estimates. If you want me to deliver some software, then that means the documentation too 
"There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult." - C.A.R. Hoare
Home | LinkedIn | Google+ | Twitter
|
|
|
|
|
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!
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
