Sure. Stop trying to cheat the customer and hire a professional to create the documents.
You've claimed it all along.
Sometimes you find a Picasso at a garage sale, too.
Ten of each, UK and US engineering texts. ...random samples?
That makes their engineering skills suspect? Good grief!
You think the entire world should be as wonderful as you (think you) are. How much of your field of vision does your nose take up?
No, I believe the first documents should come from the people closest to the customer, and then the system architects. The designers add their pound of flesh somewhere down the pipe, just as they add the rest of their value. I think JL is on target here, though he's doing all three of these jobs. the documentation has to be done *before* the design. It can't be done after. It won't be.
I didn't say she was the brightest bulb. I know my wife didn't have to have any mechanical engineering instruction to pick up a mouse and use it. Less than a minute pushing it around, without any instruction, told her everything she needed to know. Well, perhaps other than what was under the RMB.
The truth can hurt but that's not the point. You seem to think this abject lack of mechanical aptitude is somehow normal and expected. I don't know anyone under the age of 80 who had trouble learning how to use a mouse.
Good grief! They rote books about how a mouse moves? *NOTHING* else?
A whole book on mouse balls! Did you have to read it all to know which direction to point a mouse?
You keep saying that people should not be as described. Well, they are what they are, and no amount of Internet pontification will change that. You may have the last word.
Oh good Lord. You really can't read, even what *YOU* have written! You're looking down your nose at engineers because they don't live up to the standards that you think you do.
You believe people should not be as you describe them. I didn't describe people. _You_ did.
*YOU* are the one pontificating. *I* am calling *you* on exactly what you wrote in the last paragraph.
My present employer has been doing it for over 2 decades now. My personal contributions span about a decade. But we cut MSWord back to being a rather simple editor in order to achieve it (well we add in some rather simple tools with templates and some macros. Deamons i have learned to hate VBA). Wordpad could do the work if it could handle the file size.
who they are talking to as well as the types of issues that may be importan t to that audience.
efore. Writing is work, and there is an artifice to be learned. We don't teach grammar either.
en a specialty. The difference is that now there are few companies that wa nt to invest in them so it's too often left to those who aren't qualified.
There's a least one good programmer who is also a great technical writer
formatting link
formatting link
David happens to be the first graduate student (in Pyschology) of a friend of ours and we'd met him socially around Cambridge long before my boss at F isons Applied Sensor Technology told me that he wanted me to write our user manual.
By then I knew that David had set up Human Computer Interface Ltd. and I su ggested that they'd do a better job than I would. The boss talked to David, and came back very favourably impressed - a few years earlier the boss had decided that Fison's weren't going to buy up a project, largely because th e user manual was rubbish. David Johnson-Davies' mob had subsequently got t hat contract, and the example manual that they showed my boss was their ver sion of the manual, which was much better than the original.
Human Computer Interfaces went on write the manual for the IASys biosensor unit and everybody was very happy with it.
are good writers.
better written than those written in the US. I gather that this is because they still teach all students in the UK how to write, whether they want to or not.
UK universoity students are expected to write essays - of the order of ten pages long - on stuff they have been taught or have been required to study.
American Novel. We are talking about writing a simple descriptive paper. I heard from a colleague that a standard test used to qualify candidates fo r a Technical Writing job - ask the candidate to write an instruction shee t on how to tie one's shoes.
ir specialty (among a whole host of other reasons).
But it ought to be.
Not being able to write clear, complete and comprehensible text is a real d isadvantage. Having the best idea in the world isn't much use if you can't tell anybody else about it.
t exceed ten, or the teacher won't have time to do the detailed correction th at's needed. One of the big distinctions between US public (tax supported) and private (parents pay) schools is that private schools all teach how to write.
believed.
Bizarre to see krw claiming this - he's never supported any of his absolute statements, and I'd come to think that he didn't understand the concept. H e probably doesn't, and the sentence is just one that he's learned to drop into an argument at the right point. I suspect that some tax-supported US s chools will teach some of their students how to write, and that some parent
-paid-for US schools will fail some of their students in this regard, but t he general claim is plausible.
te school. If you need mathematical proof, go right ahead.
It would be statistical support for your point of view - a mathematical pro of isn't on offer for this kind of statement. Krw is unlikely to produce it .
of the technology that is being presented.
Because they are being asked to apply the skill in which they have been tra ined - writing clearly and holding the readers attention - to convey inform ation that needs to be passed on to the reader.
There's no point in training communication skills if the people trained don 't have anything to communicate. The information conveyed in a technical ma nual isn't usually all that extensive or unexpected - the art is in organis ing it in a way that lets the reader absorb it rapidly, and without too muc h intellectual effort.
o first won't work. And I've seen it tried.
struggle to generate anything useful, and so decided it would take less o f my time if I just sat down and wrote the rough first draft. One cannot j ust deliver muck because the customer verifies the usefulness of these docu ments by trying to follow them.
At the very first job I had the bosses pulled in a technical writer to writ e our progress report. He didn't understand enough of the technical content to do an entirely satisfactory job, so I rewrote it - retaining his struct ure and a lot of his wording. Either way can work.
hed document product. This is hard to do in small shops who probably don't treat documentation as anything more than a checkoff item. (Some of the m anuals I've read are abysmal! even from large multi-billion dollar corpora tions -- as if they assumed no one would ever READ them so why bother putti ng any effort into WRITING them?!)
ers are terrible writers, so they will use any excuse to avoid writing. Th e problem with my approach of attaching a Tech Writer to the programmer is that it's expensive, and you have to have some Tech Writers on staff to ass ign.
ls. People are expensive. Talented people, even more so.
Writers is exactly that engineers are able to graduate without being taught how to write a comprehensible paper.
Writing a comprehensible paper is a talent, and not the same talent as bein g able to conceive an elegant circuit, and different again from the talent of working out why a circuit isn't working and fixing that. Spearman's G-fa ctor correlates with all three skills, but most "talented" people aren't eq ually talented in all three areas. If you've got enough general intelligenc e, you can learn to do any of them adequately, but it can take quite a whil e to learn how to do any one of them really well - 10,000 hours is the oft- quoted claim. Some people can perform some skill adequately with a lot less practice, but they tend to get encouraged to apply that particular skill f or most of their waking hours.
Running a business is a different talent again ...
Talk about writing...the above is a rather decent discourse. Too bad there are NO program manuals or program "help" files that are anywhere near the ideals mentioned.
Yes, precisely. But it must have been backed up in the schools for the decade prior to university, or it would have proven impossible to get a ten-page essay out of them in university - they simply would not have it in them.
Yes. And they don't like being ignored, but by then it's too late.
Ahh, well, I was exaggerating. It that point, it seemed unlikely that there was any level of proof that would suffice, and it wasn't worth the trouble anyway.
Yes, it can work either way. But my judgement at the time was that it was less work for me if I went first. I had been involved when it was done the other way, tech writer first, and it was endless, because they didn't have anything to start with. A first draft gave them something to start with.
As you imply above, anybody with the general intelligence to be an engineer will also be able to become an adequate writer, with training. They don't have to like it. A tiny minority of these engineers will go on to write the Great British Novel, but it matters little.
ElectronDepot website is not affiliated with any of the manufacturers or service providers discussed here.
All logos and trade names are the property of their respective owners.