|
Rule 1 of good documentation:
1. Say what it is and what it does, not what it is not or what it does not do.
The reason for that is very simple: people can (and do in software manuals! Often!) fill hundreds of pages explaining what a product or feature does not do, where it is possible to explain what it does do in just a few pages -- which of those two is more useful to the struggling user who is trying to figure out how to work the damned thing?
I don't need to be told that a product or feature won't iron my shirts, clean my car, or bring about world peace; I need to know what it is and how to make it go.
What the text could have done is use a prettified version of "This product does A. To do B or C, use something else", but it is usually better to stop at "This product does A".
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Mark_Wallace wrote: 1. Say what it is and what it does, not what it is not or what it does not do.
While that is probably a good rule to have, it is not rule 1 at all!
There are many cases where explaining the limitations (ie what it does not do) is an important thing for noobs to understand early on. it also makes it clear, without being too wordy, what the scope is.
For example, hearing
"Product A does X, Y, Z"
the first question is "Ah!. But does it do W?"
This all assumes, of course, that it is somewhat logical that W is a valid function!
e.g.
MyWordProcessor has templates, uses multiple fonts, has spell checking and allows you to insert images"
Does it have grammar checking?
PooperPig - Coming Soon
|
|
|
|
|
_Maxxx_ wrote: "Product A does X, Y, Z"
the first question is "Ah!. But does it do W?" Obviously not.
_Maxxx_ wrote: MyWordProcessor has templates, uses multiple fonts, has spell checking and allows you to insert images"
Does it have grammar checking? Not in the same section of the document, so that is not being discussed.
Look in the table of contents for the grammar-checking section. If it does it, it will be in the ToC (or, if it's a much more minor function than that, the index).
Unless, of course, you want to discuss everything in a single section, which will make the document completely unusable.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Don't do it. Its disgusting food. I really feel like puking right now.
Just an FYI if you are ever tempted.
|
|
|
|
|
Been there once, in Louisiana, felt the same way. Never went back either.
Jeremy Falcon
|
|
|
|
|
I feel you pain. Ate there once....once.
|
|
|
|
|
Been to two, San Antonio and Tempe: meh.
|
|
|
|
|
The one that was most local to me lasted about two years before it permanently closed.
|
|
|
|
|
Our local one went out of business. It was very pricey, but I guess it's not good too.
|
|
|
|
|
That's too bad.
We have a few in Utah for about 15 years now, and the things I have gotten have always been good.
I usually get the barbque'd dungeness crab.
Granted there are better seafood restaurants here that I like more, but Joe's is good every now and then.
|
|
|
|
|
Agreed, me and the missus went there once .
"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
|
|
|
|
|
We had one at one of the local casinos, and for the several years it lasted it was excellent. About a year before its demise, they "refreshed" the menu and took away most of the dishes I liked, so I stopped going entirely. The replacement is something called "Bubba Gump Shrimp Shack" which, by all reports is thoroughly disgusting and extremely pricey. I have no plans to visit...
Will Rogers never met me.
|
|
|
|
|
Roger Wright wrote: Bubba Gump Shrimp Shack" which, by all reports is thoroughly disgusting and extremely pricey. Those reports would indeed be correct.
"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
|
|
|
|
|
Adjust it until he the drummer drools out both sides of his mouth.
The band I’m in have been looking for a drummer, we have had a number of good people try out. This one guy though took the cake, was pretty much an expert in everything and did his best to let us know which everything.
When we finally got around to the what do you do for a living part I told him I was a software engineer. He then asked what languages I use and I told him Assembly, C/C++, Visual Basic, C#... where upon he interrupted with There’s no such thing as C –sharp! Never heard of it. I told him it has been a part of MS Visual Studio for about 12 years or so. Oh, that C-sharp…. He says.
He didn't get the job...
It was broke, so I fixed it.
modified 4-Dec-14 12:51pm.
|
|
|
|
|
|
What do they call no-talent guys that hang around musicians?
Drummers!
I think he was going to crack a joke about no C flat, but in his enthusiasm, he got his notes confused. He just heard 'C' and went for it. He is a drummer after all...
Well actually there is a C-flat, it is called B
|
|
|
|
|
C is hardly flat.
|
|
|
|
|
The C is hardly flat, you can get some big waves out there...
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
|
|
|
|
|
Pualee wrote: Well actually there is a C-flat, it is called B
Jeremy Falcon
|
|
|
|
|
Oh, thaaaat Visual Studio. For a second there, I thought you were talking about the other Visual Studio, because that one didn't have C-sharp. Now I see what you saying.
|
|
|
|
|
Slacker007 wrote: Oh, thaaaat Visual Studio. Are you a drummer?
I only ask, because I need one.
It was broke, so I fixed it.
|
|
|
|
|
|
Didn't you know all the cool kids call it C hashtag?
"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
|
|
|
|
|
jeron1 wrote: all the cool kids call it C hashtag I should have known that, must be because I'm a guitar player.
BTW: How do you get two guitar players to play in perfect unison?
Shoot one of them.
It was broke, so I fixed it.
|
|
|
|
|
The only way to get two guitar players to play in perfect unison is if they both play bass.
|
|
|
|