Click here to Skip to main content
15,887,027 members

Welcome to the Lounge

   

For discussing anything related to a software developer's life but is not for programming questions. Got a programming question?

The Lounge is rated Safe For Work. If you're about to post something inappropriate for a shared office environment, then don't post it. No ads, no abuse, and no programming questions. Trolling, (political, climate, religious or whatever) will result in your account being removed.

 
GeneralRe: When you're very clever you are really stupid Pin
Mycroft Holmes12-Dec-20 9:53
professionalMycroft Holmes12-Dec-20 9:53 
GeneralRe: When you're very clever you are really stupid Pin
Peter_in_278012-Dec-20 10:12
professionalPeter_in_278012-Dec-20 10:12 
GeneralRe: When you're very clever you are really stupid Pin
Daniel Pfeffer12-Dec-20 20:40
professionalDaniel Pfeffer12-Dec-20 20:40 
GeneralRe: When you're very clever you are really stupid Pin
Gary R. Wheeler12-Dec-20 11:08
Gary R. Wheeler12-Dec-20 11:08 
GeneralRe: When you're very clever you are really stupid Pin
Nelek12-Dec-20 11:41
protectorNelek12-Dec-20 11:41 
GeneralRe: When you're very clever you are really stupid Pin
trønderen12-Dec-20 12:10
trønderen12-Dec-20 12:10 
GeneralRe: When you're very clever you are really stupid Pin
Mike Hankey12-Dec-20 12:23
mveMike Hankey12-Dec-20 12:23 
GeneralRe: When you're very clever you are really stupid Pin
trønderen12-Dec-20 13:17
trønderen12-Dec-20 13:17 
Agree.

But then: Today, I often wonder what kind of people write these manuals. In my files is a comic of a person lying weeping over the psychiatrists desk, who comforts him: "Don't worry! Even though you are now diagnosed as a dyslectic, you don't have to give up writing! You can still make a great career in writing computer handbooks!"

It is not only about spelling and choice of words, but maybe more about organizing the information in suitable ways, keeping irrelevant stuff away, and above all: Keeping it terse! Maybe your boss pays you by the page, but the user doesn't! And: Remember that user already has bought your product! There is no need to remind him in every second sentence how great this stuff is, that its functions are state-of-the-art, and so on. For software things: The user doesn't give a dumb that the software is written in Python and is open source! All he cares for is how to make it work to solve his problems!

I have written a fair share of software manuals, although many years ago: In those days, people paid for the manuals. So we had to give them what they paid for - what they needed. We couldn't sell them advertising material, neither for the software nor for a develop environment or software-political agenda (such as FOSS). What the user didn't need to perform his tasks, were left out.

When I see today's software documentation, ranging from online "documentation" written under the assumption that you have read the source code, to those 1500 page printed monoliths - I usually wish that I had access to the source code so I could delete all the crap. And add explanations / links for all those tribal language terms. And reorganize the stuff so that you do not have to read through five hundred pages to make sense of those ten lines that solves your problem.

To some degree I will excuse those who do not read manuals today. To a significant degree, the manuals have themselves to blame.
GeneralRe: When you're very clever you are really stupid Pin
Mike Hankey12-Dec-20 14:43
mveMike Hankey12-Dec-20 14:43 
GeneralRe: When you're very clever you are really stupid Pin
honey the codewitch13-Dec-20 0:22
mvahoney the codewitch13-Dec-20 0:22 
GeneralRe: When you're very clever you are really stupid Pin
Gerry Schmitz13-Dec-20 6:07
mveGerry Schmitz13-Dec-20 6:07 
GeneralRe: When you're very clever you are really stupid Pin
Jörgen Andersson13-Dec-20 20:29
professionalJörgen Andersson13-Dec-20 20:29 
GeneralI wish I knew JSONPath better Pin
honey the codewitch11-Dec-20 14:13
mvahoney the codewitch11-Dec-20 14:13 
GeneralRe: I wish I knew JSONPath better Pin
RickZeeland11-Dec-20 21:50
mveRickZeeland11-Dec-20 21:50 
GeneralRe: I wish I knew JSONPath better Pin
PIEBALDconsult12-Dec-20 4:07
mvePIEBALDconsult12-Dec-20 4:07 
GeneralRe: I wish I knew JSONPath better Pin
Sander Rossel12-Dec-20 0:22
professionalSander Rossel12-Dec-20 0:22 
GeneralRe: I wish I knew JSONPath better Pin
honey the codewitch12-Dec-20 2:13
mvahoney the codewitch12-Dec-20 2:13 
GeneralRe: I wish I knew JSONPath better Pin
David O'Neil12-Dec-20 5:29
professionalDavid O'Neil12-Dec-20 5:29 
GeneralRe: I wish I knew JSONPath better Pin
Mike Hankey12-Dec-20 3:31
mveMike Hankey12-Dec-20 3:31 
GeneralRe: I wish I knew JSONPath better Pin
honey the codewitch12-Dec-20 3:33
mvahoney the codewitch12-Dec-20 3:33 
GeneralI have an idea for a business opportunity. Pin
OriginalGriff11-Dec-20 11:34
mveOriginalGriff11-Dec-20 11:34 
GeneralRe: I have an idea for a business opportunity. Pin
Mycroft Holmes11-Dec-20 11:36
professionalMycroft Holmes11-Dec-20 11:36 
GeneralRe: I have an idea for a business opportunity. Pin
Marc Clifton12-Dec-20 0:40
mvaMarc Clifton12-Dec-20 0:40 
GeneralRe: I have an idea for a business opportunity. Pin
Gary R. Wheeler12-Dec-20 7:47
Gary R. Wheeler12-Dec-20 7:47 
GeneralRe: I have an idea for a business opportunity. Pin
H.Brydon17-Dec-20 16:55
professionalH.Brydon17-Dec-20 16:55 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.