Posted on 07/26/2013 10:40:44 AM PDT by Kaslin
Mwahahaha! I’m finally recognized as relevant!
High-tech has a SERIOUS problem with language/documentation. I’ve been highly-desirable in my industry since I graduated because I do what most IT people don’t: documentation.
My motto: “You can lead an engineer to documentation, but you can’t make him read it.”
Good code is its own best documentation.
As an engineering student I struggled mightily to get past the few Introduction to the humanities required courses in my curriculum. But I did learn one thing - and it sometimes seems that I must be the only one who remembers it now. And that is the etymology of the terms Philosopher and sophistry.
- sophist
- 1542, earlier sophister (c.1380), from L. sophista, sophistes, from Gk. sophistes, from sophizesthai "to become wise or learned," from sophos "wise, clever," of unknown origin. Gk. sophistes came to mean "one who gives intellectual instruction for pay," and, contrasted with "philosopher," it became a term of contempt. Ancient sophists were famous for their clever, specious arguments.
- philosopher
- O.E. philosophe, from L. philosophus, from Gk. philosophos "philosopher," lit. "lover of wisdom," from philos "loving" + sophos "wise, a sage."
"Pythagoras was the first who called himself philosophos, instead of sophos, 'wise man,' since this latter term was suggestive of immodesty." [Klein]
If you think that's hard, try to make an engineer write it for his last project when he is just begging to start the next one.
"Hi! Would you like me to interpret some 14th century Middle English poetry while you wait for your latte?"
On what planet? Scientists and engineers are eggheads. I was a history major in the 70s. It was a stupid major then, and it's even more stupid now. Learn a real skill, otherwise there is no hope for you.
You're assuming that developers document their code properly.
As someone who scripts in Powershell, I can tell you that while the big code repositories have decent documentation, pseudo-code is almost non-existent in most public repositories.
I spend more time writing pseudo-code for my programmers than I do actually writing documentation. They don't want to do it. They just want me to tell them how to translate it from what the customer wants to how it needs to be coded.
Tell ya who could use some English majors....the MSM.
The writing is BRUTAL out there!
If you work in the IT gutter like me, you’d be lucky if you get to finish a project.
Last time I spoke to my pal a writer at the software company that exported my job to Bangalore, he told me that they were considering to outsource documentation writing to Singapore.
If all you want is a skill, why go to college?
Pure tech writing, yes. I’m a systems engineer first with a BA in English and a graduate certificate in professional writing (post-grad work). I produce about 100 pages of documentation a month for my team. Granted, most of it’s screenshots, but it’s documentation that didn’t exist.
Documenting a program’s functionality for a user is easy to export. Documenting domain structure, services, networks, storage configurations, standards, policies and procedures, etc. is not something that can be outsourced with any efficiency.
There are no English majors any more. Serious literature is deader than a doornail. My tiny clique in college that communicated in Yeats, Pound, and Eliot allusions is a distant memory.
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.
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.
I used to have a haircutter who had a masters degree in History. He wasn’t all that good at cutting hair, but he always had really good stories. :-)
I find it far harder to get engineers to PRODUCE documentation than reading it.
Disclaimer: Opinions posted on Free Republic are those of the individual posters and do not necessarily represent the opinion of Free Republic or its management. All materials posted herein are protected by copyright law and the exemption for fair use of copyrighted works.