PDA

View Full Version : Any Tech Writers here???



Mike Cutler
10-30-2016, 12:58 AM
Am I the only one that believes we have a real need for a tech writer or two?

I just responded to a post about converting the wiring for a saw from 120 to 240, and wiring the plug. I gotta tell you all that I must have corrected that post a 1/2 dozen times because I would re-read it and realize I left a point out. I could do the actual job in just a few minutes, but trying to explain it is really difficult, at least for me.
I know that others must have the same problem. We know what has to happen, but putting it down in words so that someone else can easily understand it, and not potentially hurt themselves, or damage something, man that is hard!
I can do "magic" with pneumatic and hydraulic systems, but trying to help someone set up a "basic" shop air system has left me so frustrated on a few occasions, that I just kinda quit, and delete the response.
I know that there have to be others that do things for the "day job", that others in different fields could benefit from, but just have a hard time getting it into a logical format.
I re-read some of my posts and it's like they were written by a hummingbird on crack! They're all over the place.:(,

If you're a really good tech writer, what a true talent that is. I'm envious.

Brian W Smith
10-30-2016, 4:52 AM
Yeah I hear ya....but then readers do share some responsibility n'est-ce pas?Attention spans ain't exactly on the upswings these days.

I'm a book junky.One of the latest studies was about the Pothast bros. furniture in Baltimore.One seemingly insignificant point was buried in their mission statements.They were early proponents of colonial revival in late 19th century.If you're into craftsman period stuff,this is almost the opposite....maybe not full on Rococo but "classic" nevertheless.

OK,they got my attention.Part of their mission was "educating" the public.No doubt...but having spent 40+ years in the wood biz,that gets OLD!!!That's what they did for 100 years.Showing the high-end furniture buyers what they didn't know.

So,back to a readers responsibility.

Jerry Bruette
10-30-2016, 7:49 AM
I'll agree it's harder to put ideas into written form than to explain verbally. Sometimes I try to respond to a thread to help out a member and when I'm done typing I can't understand what I just typed. It is frustrating to have an answer to a question and not be able to make it go from my head through a keyboard to the internet.

Jim Becker
10-30-2016, 9:37 AM
My work in technical sales in the telecom industry requires me to "wax eloquently" both verbally and in writing, taking sometimes complex things and making them understandable by normal humans. It's something I'm generally good at. But like you, when I'm developing something for presentation, I very often have to go back multiple times to insure that I captured everything and in a logical order, too. I've found that stepping away for a bit and then going back for a complete read through helps a lot in that respect, whether it's in "white paper" format or PowerPoint or whatever. Even diagrams have to be re-reviewed because quite often some "little thing" can get overlooked that's material to the discussion.

So yea...it's an artform. :)

Malcolm McLeod
10-30-2016, 10:40 AM
So yea...it's an artform. :)

In a year on SMC, I've decided the same thing. And discovered I'm NOT an artist in this.

I have designed, installed, maintained, and repaired a variety of control systems and process equipment over the years. I do fairly well in my shop. I can can even assist a peer with how to approach a problem.

So, why do I too have to edit my posts eleventy six times to get happy with the nuances of them???

Chuck Wintle
10-30-2016, 11:58 AM
Am I the only one that believes we have a real need for a tech writer or two?

I just responded to a post about converting the wiring for a saw from 120 to 240, and wiring the plug. I gotta tell you all that I must have corrected that post a 1/2 dozen times because I would re-read it and realize I left a point out. I could do the actual job in just a few minutes, but trying to explain it is really difficult, at least for me.
I know that others must have the same problem. We know what has to happen, but putting it down in words so that someone else can easily understand it, and not potentially hurt themselves, or damage something, man that is hard!
I can do "magic" with pneumatic and hydraulic systems, but trying to help someone set up a "basic" shop air system has left me so frustrated on a few occasions, that I just kinda quit, and delete the response.
I know that there have to be others that do things for the "day job", that others in different fields could benefit from, but just have a hard time getting it into a logical format.
I re-read some of my posts and it's like they were written by a hummingbird on crack! They're all over the place.:(,

If you're a really good tech writer, what a true talent that is. I'm envious.
good tech writing ability is a gift. How to communicate difficult technical concepts in a clear and concise manner is not that easy. Many many times articles explaining tech stuff on the net leaves a lot to be desired.

Greg Peterson
10-30-2016, 6:34 PM
https://youtu.be/2fjcJp_Nwvk

Jim Becker
10-31-2016, 9:13 AM
So, why do I too have to edit my posts eleventy six times to get happy with the nuances of them???


Like your mom probably used to say... "Because" :) :D

Mike Ontko
10-31-2016, 10:29 AM
Nobody reads the manuals anyway! It's an underappreciated function in most organizations, most often seen as a necessary evil (because some of those fussy customers insist on having supporting information) rather than as a way to connect with your community of users.

After a stint in the Navy, I worked my way through school doing technical writing and illustration. I had originally targeted engineering as my career goal (after six years as an electronics technician, a BSEE seemed to be an obvious path forward) but realized just before declaring my major that at the end of my undergrad work, I'd have to restart at the bottom of the career ladder as a junior engineer rather continue growing with my experiences as a technical writer/communicator. So, I got my degree in Technical Communication/Human Centered Design & Engineering. I tell people the degree was intended to justify my work over the previous ten years. More importantly, it has allowed me to grow beyond writing manuals and service procedures and get into other areas of information design and management.

And I do think of it as a craft of sorts--using language, syntax, typography as the basic tool set, and a few key tenets of visual design to create something that can clearly be understood and interpreted in the context in which it was intended.

William Adams
10-31-2016, 12:49 PM
It's difficult.

I'm disappointed that technology hasn't provided better tools, or more interesting mechanisms for conveying information.

Most interesting project I've worked on this far was the assembly instructions for the Shapeoko 2: http://shapeoko.github.io/Docs/

The SVG graphics when opened up in a window of their own are interactive --- one can click on a part # / name to highlight/remove the highlight:

http://shapeoko.github.io/Docs/content/tPictures/PS20028-100.svg

Unfortunately, there doesn't seem to be any interest in continuing to use / improve upon such.

Mac McQuinn
10-31-2016, 2:55 PM
When I received my degree, as opposed to taking another English 101,102, etc. class, I took technical writing. I enjoyed it and found it more challenging than the normal college English class. I was fortunate to work around an large amount of heavy machinery, providing me material to use in writing instructional papers on. It does take an ability to clearly break down functions in specific order without omitting steps and details. My degree is in Residential Construction.
Mac

Bill McNiel
10-31-2016, 3:53 PM
I have wondered for years why foreign manufactures don't hire someone speaks English as their native tongue to final proof the "included instructions".

Prashun Patel
10-31-2016, 3:55 PM
I have wondered for years why foreign *manufactures* don't hire someone... to final proof the "included instructions".

manufacturers?

Sorry, couldn't resist a little bit of irony!!! ;)


But seriously, my kids' elementary school is on this big kick to have kids read more technical writing to prepare them for a competitive world. This has them explaining anything and everything in words. Their math worksheets are half real problems, half reflection and explanation. Now, I'm all for showing your work, but my son spends the most time on these abstract questions. I'm all for kids writing to express themselves, organize their thoughts, and grow intellectually, but there are just better ways both for the author and the student to communicate things like wiring or playing "Chestnuts Roasting on an Open Fire" on guitar. We are now in a place where video and spoken word are an efficient and economical way to communicate certain concepts.

Mike, there's a reason you had to re-edit your post a million times. I bet you could have recorded and narrated a far more informative and concise video on the subject with less work on your part. The sooner we all embrace this wonderful way to teach, the better.

Mike Henderson
10-31-2016, 5:52 PM
manufacturers?

Sorry, couldn't resist a little bit of irony!!! ;)


But seriously, my kids' elementary school is on this big kick to have kids read more technical writing to prepare them for a competitive world. This has them explaining anything and everything in words. Their math worksheets are half real problems, half reflection and explanation. Now, I'm all for showing your work, but my son spends the most time on these abstract questions. I'm all for kids writing to express themselves, organize their thoughts, and grow intellectually, but there are just better ways both for the author and the student to communicate things like wiring or playing "Chestnuts Roasting on an Open Fire" on guitar. We are now in a place where video and spoken word are an efficient and economical way to communicate certain concepts.

Mike, there's a reason you had to re-edit your post a million times. I bet you could have recorded and narrated a far more informative and concise video on the subject with less work on your part. The sooner we all embrace this wonderful way to teach, the better.
I much prefer the written word to video. The problem with a video is that it's difficult to skip to what I want to see and later, to find something I want to review. Basically, I find video to be waaaay too slow.

With written instructions - with pictures - I can go as fast as I want to and I can skip ahead easily. Also, I can later find the one thing I want to review easily.

I often receive a email touting some instruction and then when I look deeper, its a DVD and not a book. I delete the message at that time.

Mike

Chris Padilla
10-31-2016, 7:01 PM
YouTube rules, Man! :)

Bill McNiel
10-31-2016, 8:31 PM
manufacturers?

Sorry, couldn't resist a little bit of irony!!! ;)

.

Irony or humour?

Michael Dye
10-31-2016, 8:32 PM
Just when I thought we could have an intellectually stimulating conversation, somebody says "YouTube rules, Man". I believe the only thing that could have been worse would be "Twatter rocks, dude". Fortunately for me, my father was driven by the need to speak and write clearly and intelligently. That was driven into our skulls daily. Consequently, when I joined The Boeing Company as a test pilot, my writing abilities were quickly discovered and I found myself, on occasion, being asked to help in the Tech Pubs department. Today, I am proud to say, much of my writing is included in 737,747, and V-22 Osprey emergency procedures manuals.

I enjoy reading and writing very much. It gives me great pleasure to see my teen-aged kids consuming books with the same passion that I have always had. More importantly, I enjoy coming on to the different forums and joining in on some of the more spirited, intelligent discussions. Oh, one more thing..........I've been very lucky in life. I spent my life flying, helicopters to start with, followed by airplanes. Started young, got my aeronautical engineering degree by the time I hit 30, and got out of the business at 55. In a business that is unforgiving of mistakes, I wake up every day, grateful that I survived.

Now, this forum takes up quite a bit of my free time. It is a source of incredible depths of information. Thanks to all of you for giving an old man an additional reason to get out to the shop every day.

Chris Padilla
11-01-2016, 12:40 AM
And what is wrong with You Tube, Michael? I happened to have learned A TON with that video outlet. Between here and there, why not soak up information any way you can get it? You ever watch The Wood Whisperer or repeats of Norm on The New Yankee Workshop? Or heck, watch Izzy Swan churn out some near genius contraptions. Excellent stuff. Embrace technology...don't push it away. After all, you are on a forum so that's a good start....

Jim Koepke
11-01-2016, 1:15 AM
In college one of my classes was Technical Writing. It is a difficult thing to stay clear and on point in writing. I give it my best, but have only written one manual for pay.

I agree with Chris on Youtube and so many other sources of information available to us through technology as valuable sources of knowledge. The problem is it is as easy for an idiot to publish as it is for someone who knows of what they speak.

The other problem is a lot of things live forever, or so it seems, on the internet. Some of my older 'how to' posts could use revisions. Alas, I have no editing power over them. It would also be a chore to correct all of them.

jtk

Ryan Mooney
11-01-2016, 1:58 AM
The first rule of editing is that it's not how much you can add, but how much you can remove.

This is a rule I've often neglected to the detriment of my readers.

Jim Koepke
11-01-2016, 11:28 AM
The first rule of editing is that it's not how much you can add, but how much you can remove.

This is a rule I've often neglected to the detriment of my readers.

The origin of this escapes me at the moment, "Words should be weighed, not counted."

Google sources it to being an old proverb from various sources.

jtk

Ryan Mooney
11-01-2016, 12:53 PM
The origin of this escapes me at the moment, "Words should be weighed, not counted."

Google sources it to being an old proverb from various sources.

jtk

I believe the origin of the quote (heavily paraphrased in my case) is generally credited to:
https://en.wikiquote.org/wiki/Antoine_de_Saint_Exup%C3%A9ry
https://en.wikipedia.org/wiki/Antoine_de_Saint-Exup%C3%A9ry


It seems that perfection is attained not when there is nothing more to add, but when there is nothing more to remove.
As translated by Lewis Galantière: ... perfection is finally attained not when there is no longer anything to add, but when there is no longer anything to take away ...


I'm sure the concept likely pre-dates him but no idea.

edit: Unsure on the words quote - that is likely much much older.

Chris Padilla
11-01-2016, 1:10 PM
Einstein is purported to have said, "Everything should be made as simple as possible...but not simpler."

Prashun Patel
11-01-2016, 1:47 PM
Irony because your post mentioned proofing the manuals, when the post had a type-o. 100% in jest, I'm sure you know! ;)

Prashun Patel
11-01-2016, 1:49 PM
Nobody said "You Tube rules, Man." I only meant that there are multiple ways to communicate efficiently now.

If the purpose is to preserve the wonderful art of writing, then I fully support that. If the purpose is to concisely and effortlessly teach and communicate, we'd do well to consider all options available rather than turn noses up at it and consider some a medium for the sadly naive.

Chris Padilla
11-01-2016, 3:27 PM
I said it, Prashun. :)

Roger Feeley
11-01-2016, 8:53 PM
I work at the bleeding edge of technology. I write protocol decoders for a company that makes packet sniffers. At one time or another, I have dismantled communication protocols for Bluetooth, USB, wifi/Ethernet, NFC, sad cards, and just about every industrial protocol. I don't see myself as an expert in any of these, it I am an expert in reading specifications I don't understand..yet.

my pet peeve is specs and explanations that pre suppose the you already understand the subject. Many experts are unable or unwilling to avoid the jargon and acronyms they use with each other every day.

in my writings and presentations, I make a conscious effort to speak in plain English. When I must use jargon, I always stop and explain the term and why I must use it. Our customers seem to appreciate it.

another thing I'm careful about are examples. Many examples include things you have to learn and remember before you can get to the point being made. I frequently use cartoon characters and Shakespeare in highly technical discussions.

oh yeah, if you need a protocol analyzer, call Frontline Test Equipment. If you have a proprietary protocol, I'm your guy.

Bill McNiel
11-01-2016, 9:51 PM
Irony because your post mentioned proofing the manuals, when the post had a type-o. 100% in jest, I'm sure you know! ;)

I'm afraid my warped sense of humour, or do folks prefer the Americanized "humor", has failed miserably. I probably should have made it more obvious that I was providing an example of how language translation programs can, and do, fail, although I did provide yet a second attempt at clarification. The "mistake" was not a "type-o", it was intentional but apparently too veiled to be effective. My equally warped wife didn't think anyone would get the original post as it was too subtle but I just had to try . Kudos to Prashun.