Free Republic
Browse · Search
News/Activism
Topics · Post Article

To: rarestia

The old problem with software documentation is that it’s written by documentation writers, and not by the engineers who write the code, and are typically inarticulate, impatient and secretive when interviewed by the writers. In my career, writing code for internal use (by those same engineers, by the way) we wrote our own documentation, and it was better than any published docs I had ever seen, including the docs for use by the company customers. Our motivation was simple: we didn’t want to explain ourselves over and over again. RTFM was our usual answer.


16 posted on 07/26/2013 11:10:35 AM PDT by Revolting cat! (Bad things are wrong! Ice cream is delicious!)
[ Post Reply | Private Reply | To 2 | View Replies ]


To: Revolting cat!

Problem with engineer documentation is that it’s not functional or practical for users. I’m guilty of it myself. I have Visio diagrams, Excel spreadsheets, Word documents with procedures all over my local and network disks. My job is to consolidate it for presentation to our non-technical executives. They love that stuff.


18 posted on 07/26/2013 11:13:21 AM PDT by rarestia (It's time to water the Tree of Liberty.)
[ Post Reply | Private Reply | To 16 | View Replies ]

To: Revolting cat!
... writing code for internal use (by those same engineers, by the way) we wrote our own documentation, and it was better than ...

My group did the same. Users rarely had to call to ask how to make something work... it was all covered. We usually only heard something if a bug in the code popped up.

34 posted on 07/26/2013 11:31:45 AM PDT by ken in texas (The Obama Excuse: They never told me and I didn't ask.)
[ Post Reply | Private Reply | To 16 | View Replies ]

To: Revolting cat!
RTFM was our usual answer.

I have that on my coffee mug.

46 posted on 07/26/2013 12:01:11 PM PDT by tacticalogic ("Oh, bother!" said Pooh, as he chambered his last round.)
[ Post Reply | Private Reply | To 16 | View Replies ]

Free Republic
Browse · Search
News/Activism
Topics · Post Article


FreeRepublic, LLC, PO BOX 9771, FRESNO, CA 93794
FreeRepublic.com is powered by software copyright 2000-2008 John Robinson