Friday, May 30, 2008

Manual

Today I am free write the most outrageous ideas that cross my mind. They say that nobody reads the manuals. I have put the title "Manual" and now anything I write will be read by myself only. Yes, I read the manuals and sometimes I even read them twice. I don't like doing it, yet it's a precious activity. If I am going to use a program, I know I can't learn it by trial and error, it's only a waste of time. I look for the manual and study it.
A well-written manual it's hard to find today. If people were to choose program on the clearness of their manuals, the documentation writers would be as rich as Bill Gates and our kids would aspire to become doc writers instead of football players. That's not the case. I myself have maintained, for years, that programmers can't neither be the testers nor the doc writers of their own programs. Today I have changed opinion, not because my idea was bad, but just because a bad manual is better than no manual.
Let's hope that, at least, the manuals are up-to-date. Have you ever found a manual that refers to an old version of the program? It easily happen that they change the program, even drastically, but forget to update the manual. That's the worst thing that can happen. A less sad situation, yet still annoying, is when you buy the Mac version of a program and all the figures of the manual refer to the Windows version.
Are they to blame? They are not, because they have been told that nobody reads the manuals, so why should they invest time into the job of writing manuals? Why? WHY?
After years I have found the answer. I had to. I was writing pages over pages, and receiving the confirmation, day after day, year after year, that nobody was reading them. They still use to call me and ask: "where can I found the manual?". They keep printing it, losing it and printing it again, but never finding the time to read it. I stopped and told to myself: "Either you find valid a reason, in the next 5 minutes, for doing it, or cease writing manuals forever". In the next 2 minutes I realized that, quite often, I consult my own manuals because I forgot how my programs are supposed to work. Consulting the manual is simpler and faster than reading the code of the program
Now I write manuals for myself. I attach the manual to the product because you can't sell a program without any manual (and there's even the risk that somebody checks if the manual actually describes the enclosed program or a different one), but I write the manual for myself. I am not proud of it but, hey, you don't know how difficult it can be to write a good manual.
After years of frustration I finally have a thing in common with Scaruffi. (I seem to remember that he once stated, in an interview, that he writes a lot because his memory has always been week; but being my memory week too, I may be confusing him with another person...).

0 Comments:

Post a Comment

<< Home
http://nmr-software.blogspot.com/2008/05/manual.html
nmr-software.blogspot.com
crawl=CC-MAIN-2018-05
22700
application/http; msgtype=response
sha1:4MUGNGPHFCD7EGKLTSS6QNJHKQXF62MD
<urn:uuid:a4db330a-7654-4898-a1c9-6907b94e2619>
2018-01-22T12:26:41Z
216.58.217.161
application/xhtml+xml
sha1:XDYEQW44B4NW2GPSLNLZ3I4V5P43FO4C
<urn:uuid:59c8c8ed-37b2-419c-be2c-fe3f6fe963c3>
http://nmr-software.blogspot.com/2008/05/manual.html
response
<urn:uuid:c271cf94-057c-44b8-a304-4301b722c3f0>
robots: classic
hostname: ip-10-233-143-46.ec2.internal
software: Nutch 1.6 (CC)
isPartOf: CC-MAIN-2018-05
operator: Common Crawl Admin
description: Wide crawl of the web for January 2018
publisher: Common Crawl
format: WARC File Format 1.0
conformsTo: http://bibnum.bnf.fr/WARC/WARC_ISO_28500_version1_latestdraft.pdf