Re: Fraction

Ethan Merritt wrote:


Well, someone would review your patch before applying it.
At worst they would decide not to apply it all.

Of course.


However, I am not sure if you understood what I meant. Whats the use of entries in the index at the end which do not exist in the text?

You were suggesting that a search for "division" would not currently
turn up anything. That is true, because there is no existing section
in the documentation whose title is "division". But the 3rd paragraph

I am not sure I understand this, are the words in the index currently only the ones which may occur in section headings?


under "expressions" explains exactly this point about integer division
versus floating point division. By sticking the line
=division
in front of this 3rd paragraph, you would generate an index entry
that points right to the relevant place.

Division was just an example, but what I wrote was meant to give a general situation.


Please do not take this in the wrong sense. I know if I am creating an open source program, I would always point out to feature requesters to "create a patch and send it" if I am not interested in that feature ... which many times is just a politer way of saying "if you want it, go do it yourself, who is stopping you?". I hope that wasn't the case here.

I thought your point was partly that a developer is not the best
person to write introductory level documentation, because too many
things are "so obvious" that they literally go without saying.

er .. not entirely. The things that go without saying needn't be like that if the author of a code actually thinks about it while writing the documentation -- but for this a programmer needs to realize this himself. And given a stereotypical unix programmer (others too I suppose), doing that is the last thing on earth -- an attitude very very common till the nineties. For example, if I never thought about this, I would just document the mechanics of my code in doxygen. But since I keep this in mind, my resulting documentation is much more user friendly in the end; with equations, links and figures and a PDF output to go with it.


Conversely, a new user who has just struggled to figure out something
may be an excellent person to write a sentence or two for the docs
that may save the next guy from suffering that same struggle.

Yup. I always keep this in mind when I post queries on newsgroups and mailing lists. If I find a solution, I post it as well along with a description which is designed to use related words in the hope that a future user may find it while googling for those words or phrases. Heck, sometimes I even put a bunch of keywords by themselves if I cannot use all of them in sentences. I consider that as another documentation/help channel. No matter how precise documentation you have, the first try is, in all likelihood, going to be a search on the web. If a person can have a basic example and rough explanation there, it is significantly much more easier for him to follow it up by reading the documentation which would make more sense faster.

Consequently, the "RTFM" replies in newsgroups and mailing lists are more or less useless in this regard. How many times has someone searched for RTFM in google as a means for help?


Adding index entries for things that are hard to find is even easier.
You could post here saying "please add an index entry 'division' for
the 3rd paragraph in the section labeled 'expressions'".
But multiply that by a couple dozen and I'd much rather just have a
patch that contains all those suggestions in one go.

I perfectly understand this and agree.


\me goes off to add an index entry for "division"

Many thanks!

regards,
->HS
.

Relevant Pages

  • Re: GoTo in Java
    ... I'm saying that is a hypothetical which, so far, I have not encountered ... methods of user interface and documentation, ... It would be wise to trap overflow and ensure ... ADD INCREMENT TO COUNT ON OVERFLOW CALL COUNT-ERROR-HANDLER ...
    (comp.lang.cobol)
  • Re: Where is the notificiation about IE zero day vulnerablity?
    ... You are refusing to do research and are ... Saying 'it's there, find it' is easy. ... A man who loves/believes/is passionate about what they speak of is willing ... and able to present documentation at a moments notice - backing up what they ...
    (microsoft.public.security)
  • Re: Measuring time differences
    ... > use in Microsoft Windows than Microsoft do you are giving BAD advice. ... used to compare times. ... The MS documentation simply says you shouldn't ... I'm not saying its not there, ...
    (comp.lang.c)
  • Re: Can anyone tell me
    ... should be used even if it is less efficent because it is self documenting. ... I'm not saying documentation is required. ... ByRef, you should just know that changing the value in the called procedure ...
    (microsoft.public.vb.general.discussion)
  • Re: I cant believe how complex this Format SDK is...
    ... I've been a programmer since '80. ... provides me with an unbiased perspective on the docs and APIs. ... Overall I think the documentation is reasonably good, ... run my app in the debugger, such as first-chance exceptions when using ...
    (microsoft.public.windowsmedia.sdk)