You and Your - how to stop technical authors using these!

[RamonS]

And I am neither a Yankee nor a Tommy, just an old Kraut.

[Andrew]

Goodness.
I knew the yanks are a very traditional people, but this is ... - I'm afraid even the brits I know are more innovative and open ...

I'm not really interested in a culture war. Suffice it to say your characterization of Americans as "very traditional" (and your characterization of British in general) seems like an ugly (and almost certainly *wrong*) stereotype.

[i-tietz]

And I am neither a Yankee nor a Tommy, just an old Kraut.

Living in the US. Producing for the US. Working for US companies.
Or is that not right?

[i-tietz]

I'm not really interested in a culture war.

War? I learned to give credit to different cultures in the target group. That has nothing to do with "war". And my opinion originates from what you two wrote in this thread ... so actually it's your experiences - not mine. I never produced for US citizens.

[i-tietz]

There are many places where traditions blur things. Typical example is a bank. The tellers are expected to be dressed nicely and look businesslike. A dude with tattoos, ripped jeans, muscle shirt, bling, and flip flops is most likely as capable in banking as a greased up guy, but honestly, which one would you pick?
Same applies to documentation. Some audiences just prefer / expect the bland and dusty robotic approach. And heck yea, tech writing is marketing. The documentation is as much part of the whole product as the box it comes in is. Nevertheless, I think we agree that this discussion is about nuances. If the meat isn't there then the gravy doesn't do much.

Ill-fitting comparison - the target group of bankers are not professionals, but laymen. This is very clearly 100% marketing - even literally: They present themselves to the market and try to sell their image and/or their services.

But this makes me come to the conclusion: The only real difference I see is "capital equipment" or "consumer goods".
For consumer goods I wouldn't only allow but even expect a marketing aspect in documentation.
With capital equipment there isn't anything like that - the target group her are professionals. The look and feel is not something they accept as criterion as long as functionality and price aren't identical - and it hardly ever is ...

[Andrew]

And my opinion originates from what you two wrote in this thread ... so actually it's your experiences - not mine. I never produced for US citizens.

Neither I nor David were talking about "Americans" (which I assume was the referent of "yanks"). We made references to a few possible markets where the use of "you" might be be better avoided (or it might be no problem at all; you have to know your users). It has nothing to do with how easy it is to understand the documentation, and everything to do with how those who read the documentation *perceive* it. You can write with and without "you" with roughly equal clarity; the main difference is in tone.

[i-tietz]

David wrote "There are many places where traditions blur things." You agreed writing "Precisely."

Coming to the conclusion that you were talking about american users was not allowed? Interesting. You have experience in writing for e.g. french, japanese or indian users instead of leaving that to native translators? Then I take everything back and argue the converse.

[Andrew]

David wrote "There are many places where traditions blur things." You agreed writing "Precisely."

Coming to the conclusion that you were talking about american users was not allowed? Interesting. You have experience in writing for e.g. french, japanese or indian users instead of leaving that to native translators? Then I take everything back and argue the converse.

Perhaps I misread David's post, but by "places" I thought he meant "industries" or "organizations" not countries.

[i-tietz]

Perhaps I misread David's post, but by "places" I thought he meant "industries" or "organizations" not countries.

Concernign perception culture is a lot more powerful than profession. I honestly think that an engineer in a nuclear power station in Japan and in the US behave and perceive documentation differently.
Assuming that personnel in a nuclear power station is different from personnel of a solar cell producer is the next step - I just moved to the closest conclusion ...

[RamonS]

Yea, more like that. Some go for the more formal style while others don't mind the buddy tone. That is a matter of both industries and cultures. And yes, it also comes packaged with prejudices. Some time ago I was interested in opening an online bank account. The documentation that was sent over was in an extremely casual tone and tried hard to be funny and entertaining. While I appreciated the effort I took my money somewhere else.
As far as (technical) documentation goes, it matters who it is intended for and how a specific style is perceived. I think that as a (tech) writer one has to adjust to that rather than insist on a personal preference. We don't write for us, but for others and the docs are a written form of customer interaction. For the same reason we edit and spellcheck and do all kinds of things, which we might not do when we throw together a readme for a quick'n'dirty file converter that is published as FOSS (btw, some FOSS projects have excellent documentation).
That said, I cannot speak for all industries and (company) cultures having written for US, Canadian, UK, and German customers, but I am sure that there are differences. Another example where nuances count would be in writing two English versions of the docs, one for US and one for UK. I think that is the right thing to do, but typically it is not done for cost reasons. Will someone from Manchester understand the US version of the help? Of course, but would he/she prefer a British version? I am rather convinced that this is the case. Or a German customer may be OK with the English documentation, but probably prefers a well-written German version. I don't think that an English speaking customer would be OK with only German documentation (for valid reasons).
So in the case of you and your it depends on the audience and if that doesn't matter on personal preference. In regards to personal preference there is hardly a right or wrong. In regards to preference of the audience I'd argue that there is a right or wrong. And the right way could well be something we find awkward. For example, some legalese is written in all caps in click throughs. While some may consider that as 'yelling' lawyers use it purely for emphasis that is mandate by law or became necessary due to litigation. Does that mean that in all of the documentation every paragraph with important content needs to be all caps? Most likely not, because it suits a different purpose.
I'd omit the you and your in docs unless I am told otherwise knowing quite well that some may find that a rather stupid way to write things. I think it uses less words and may be easier to comprehend that way. Even the slightly weird sound of it may foster more reader attention. But it also could make someone mad and they throw my docs into the digital trash can. If it would be so easy to do what we do then we would not have this discussion and just anyone could do tech writing. Good tech writing is an art form.

[ccardimon]

Good tech writing is an art form.

Amen to that.

[i-tietz]

And yes, it also comes packaged with prejudices. Some time ago I was interested in opening an online bank account. The documentation that was sent over was in an extremely casual tone and tried hard to be funny and entertaining. While I appreciated the effort I took my money somewhere else.

Aha. So first you complain about prejudices and then you give in to them - just because a banker is wearing a suit and has visited the odd rhetorical course you give him your money ...
That comes from the deepest depths of evolution and it's a mechanism we don't need in our world anymore. In fact it's rather dangerous for our existence, because it can easily be used to mislead us - just ask those US citizens who lost their houses in the past 3 years and all those people all over the world who are now left without a pension, which will cost them decades of their life and their children and grandchildren a good education.
But maybe that's the way evolution is working now - eliminating those who don't grow beyond their instincts. So go on judging by "tone" ...

[Andrew]

Aha. So first you complain about prejudices and then you give in to them - just because a banker is wearing a suit and has visited the odd rhetorical course you give him your money ...

This is a misunderstanding of the point. We advocated understanding your users, and adjusting your tone based on that understanding, which is the *exact opposite* of a prejudice.

[i-tietz]

Good tech writing is an art form.

Amen to that.

TAs are no artists - they are not allowed to do l'art pour l'art. J.K. Rowling might be an artists or Hemingway or Goethe. But if those are our rolemodels for our job, something has gone awfully wrong. Good TD bows to ratio. Bad TD just like bad programming bows to intuition.
If you wanny be an artist, write novels.

[ccardimon]

TAs are no artists

I respectfully disagree. First we must become craftsmen, then we become artists as our skills improve. That goes for dog groomers and many others, as well as technical writers. My two cents.

[RamonS]

Aha. So first you complain about prejudices and then you give in to them - just because a banker is wearing a suit and has visited the odd rhetorical course you give him your money ...

This is a misunderstanding of the point. We advocated understanding your users, and adjusting your tone based on that understanding, which is the *exact opposite* of a prejudice.

Exactly! I do a lot of things professionally that I disagree with personally and as an SME, but customers want to do it the other way. In those cases expert opinion does not count. Nevertheless, in most cases it comes back to me, because the customer's approach crashed and burned. But then again, there are cases where the customer is indeed right. And I am very glad in those cases that I did not push through as a blockhead. Just for those few cases it is well worth dealing with all the other cases.
Sometimes I am a customer and I deal with documentation and if I dislike how someone talks/writes to me I take that into consideration. For example, several reputable magazines now have an online edition. I read many of these articles as they keep me informed quicker than waiting for the print version (which often has other content). Best example is Computerworld, more and more of the online articles are badly written and riddled with spelling errors. I have a tough time taking those articles seriously. If a journalist isn't even bothered by at least reading once through an article before publishing it, then it makes me wonder which care is taken with reading sources that get quoted and interpreted in these articles. Or also the incorrect use of acronyms, such as ATM machine, LCD display. This carelessness in writing reflects badly on a magazine that is around for decades and built a positive reputation.
Writing badly and / or not addressing the audience as they expect it is not going to work out. No matter if I like it that way or not. I accept that as a fact and I understand it, because as a customer I do not behave any differently.

[RamonS]

Good tech writing is an art form.

Amen to that.

TAs are no artists - they are not allowed to do l'art pour l'art. J.K. Rowling might be an artists or Hemingway or Goethe. But if those are our rolemodels for our job, something has gone awfully wrong. Good TD bows to ratio. Bad TD just like bad programming bows to intuition.
If you wanny be an artist, write novels.

I also disagree. It is like saying Beethoven is not an artist, because he could only deal with 7 pitches per scale. TWs are confined in a similar way, yet some manage to do marvelous and creative work within these limits. And that goes beyond knowing the tech writing tools and have some decent language skills. One needs to know the industry, the various groups to be addressed, and understand how the company wants to present itself towards customers. If a TW doesn't get that then he or she is nothing more than a formatter who can make stuff look pretty, maybe.

[i-tietz]

I also disagree. It is like saying Beethoven is not an artist, because he could only deal with 7 pitches per scale. TWs are confined in a similar way, yet some manage to do marvelous and creative work within these limits. And that goes beyond knowing the tech writing tools and have some decent language skills. One needs to know the industry, the various groups to be addressed, and understand how the company wants to present itself towards customers. If a TW doesn't get that then he or she is nothing more than a formatter who can make stuff look pretty, maybe.

So if a car mechanic knows the principles of how things work even in modern cars so well that he finds the origin of each and every fault, he's an artist? If a physician knows more symptoms of more diseases and more cures than 99% of his colleagues, he's an artist? Even if a photographer knows everything about making photographs and the chemistry of developing photos I wpould not call him an artist, because you gotta have that "eye" to see the subjects that make those photos fantastic.
Sorry, but all that has nothing to do with art, just with knowledge and invested labour. There's a difference between doing a good job and being an artist.
Where does that thinking come from? Because a study that has to do with language ends with a BA or MA of Arts?

I met TAs who think the way you do, too: In a discussion about new documentation concepts they come up with the "argument": "I think so." They wouldn't even give in to arguments like "Studies have shown that." - not even if you hand the studies out to them. They always know better without having proof or REAL arguments. And I also know tons of developers who think that way about their job, too. And they pretty often work inefficiently and deliver bad quality for the simple reason that they think they don't "need" checklists and rules that come from decades of experience. Then somebody (happened to be a developer, too) dares to present them rules like "Write comments when you check in a file, even if you only changed the background-color of a control from red to white", and they look like they would want to jump straight at that other developer. "How can you dare to restrict my creativity with something redundant like checklists or rules." - that's what they say more or less directly.
Don't tell me you never cursed when working together with that sort of developer ...

But I'm beginning to understand why such a lot of people twitter as if their life was depending on it. They really need to ignore that 75% of all tweets die away unread and unnoticed. In a job I find that sort of behaviour unprofessional in any case. Real professionals don't have problems with rules and checklists to ensure a certain quality level. We're no artists - we're craftspeople.

[RamonS]

Sorry, but all that has nothing to do with art, just with knowledge and invested labour. There's a difference between doing a good job and being an artist.
Where does that thinking come from? Because a study that has to do with language ends with a BA or MA of Arts?

Exactly! Art ist not just painting pictures. Art is a form of proficiency that is above average and requires specific skills. In regards to tech writing, the art is to produce excellent documentation within the confinements given. And there are plenty, such as time, money, customers, users, employers, coworkers, industry standards,....

I met TAs who think the way you do, too: In a discussion about new documentation concepts they come up with the "argument": "I think so." They wouldn't even give in to arguments like "Studies have shown that." - not even if you hand the studies out to them. They always know better without having proof or REAL arguments.

And that is why I mentioned several times that I expect from a good TW to know the industry, the terms of the trade, the audience, and the effects of all the confinements mentioned above. The fact that there are so many obstacles to master makes it difficult. As a good TW you need to know the technical aspects in an out, be a good writer, and have passion for what you are doing. If writing docs is just a job that pays money and everything else doesn't matter, then not much good can come from it other than a paycheck. But that is true for any profession.

And I also know tons of developers who think that way about their job, too. And they pretty often work inefficiently and deliver bad quality for the simple reason that they think they don't "need" checklists and rules that come from decades of experience. Then somebody (happened to be a developer, too) dares to present them rules like "Write comments when you check in a file, even if you only changed the background-color of a control from red to white", and they look like they would want to jump straight at that other developer. "How can you dare to restrict my creativity with something redundant like checklists or rules." - that's what they say more or less directly.
Don't tell me you never cursed when working together with that sort of developer ...

I worked with those developers. The good thing about them is that they either quit soon or get fired. Developing software is also an art, because there are also many confinements and challenges that need to be mastered. And doing that well requires special persons who not just have coding skills, but understand the business and care about the users. When coders ignore the coding standards and stop thinking about the customers they intentionally ignore the confinements. Sometimes that may work out, but often enough it does not.

But I'm beginning to understand why such a lot of people twitter as if their life was depending on it. They really need to ignore that 75% of all tweets die away unread and unnoticed. In a job I find that sort of behaviour unprofessional in any case. Real professionals don't have problems with rules and checklists to ensure a certain quality level. We're no artists - we're craftspeople.

I don't know what Twitter has to do with it. I don't use it as my weakness is not being concise. I cannot get my point across in 140 characters. But maybe others can't either, which makes many of the tweets, well, pointless.
As far as being craftspeople, in that case any TW could do your job. I doubt that is true. Some may be able to fill in the role, but you are not replaceable by just any schmuck that gets picked off from just anywhere. In other words, as a good TW you bring something to the table that is unique and that is hard to find. Otherwise your employer would have long ago replaced you with someone who does the same craft for less money.

[nickatwork]

I dunno,
I'm sturggling to see the 'art' in all of this. Perahps it's all to do with how we are definnig art.
But to me, it's a creative spontaneous process, where anything is possible, there are no limits, no boundaries. Your imagination is the border.

In technical writing, there are so many constraints, as have been mentioned, that it limits nearly everything you can/could/want to do because you have to work within them.

Sure you can think outside of the box etc to accomplish something. But this is true for pretty much everything, if I look around my office the same principal could be applied to any role I see people doing. From developers down to support line staff.

Just because we are producing a 'physical' product in our work, I don't think that qualifies it as art.

[LTinker68]

I don't think it's art as in creative so much as there's an art to doing it well. Taking numerous documents or blocks of content from SMEs, marketing, sales, support, programmers, etc., refining that content so it can be easily consumed and understood by the end user, adding info that the others might not think about or present it in a different way, adding images, media, etc., to aide in comprehension, and so on and so on.

To put it another way, editors clean up the notes for one musical instrument. Tech writers compose a symphony for multiple instruments.

[ccardimon]

To put it another way, editors clean up the notes for one musical instrument. Tech writers compose a symphony for multiple instruments.

Nicely put.

[i-tietz]

If your "artist developers" always quitted, consider yourself lucky. I am in the business for about 30 years now and they just won't go away or rather: they keep turning up - not necessarily as the same person, but there's plenty of them. Evolution is just too slow for me to bear ...
Too many people need that conviction for their self-confidence, but it's just good auto-suggestion ...
I don't consider myself an artist - I'm just a pro.
And I'm fed up meeting people who think they can ignore all sorts of restrictions for the sake of "creativity" and personal opinion - that's a costly spleen.

[RamonS]

Not disagreeing here, but it seems that whoever is in charge of hiring developers doesn't seem to pick the right people. In my experience it is that they eventually dig a pit so deep with their creativity that their code becomes entirely unmaintainable. Even the developer who wrote the code no longer gets it. Just went through a complete redesign due to that and by keeping things simpler, using established components, and focusing solely on the goal to accomplish we now have something that looks a wee bit flashy, but in return now finally works and does not use fancy code that doesn't do anything within the 10,000 lines.
I guess it all depends on the market position the company is in. After all, people bought Microsoft Vista and W7 despite its obvious suckiness.

[i-tietz]

Not disagreeing here, but it seems that whoever is in charge of hiring developers doesn't seem to pick the right people. In my experience it is that they eventually dig a pit so deep with their creativity that their code becomes entirely unmaintainable. Even the developer who wrote the code no longer gets it. Just went through a complete redesign due to that and by keeping things simpler, using established components, and focusing solely on the goal to accomplish we now have something that looks a wee bit flashy, but in return now finally works and does not use fancy code that doesn't do anything within the 10,000 lines.
I guess it all depends on the market position the company is in. After all, people bought Microsoft Vista and W7 despite its obvious suckiness.

All it needs are project managers who have never been developers or have been developers long ago, means: They cannot really supervise development or developers.
Especially if you do individual software (for a specific customer) you don't really do revisioning often - you do new features, but don't change anything old. And if you really need to change sth old and don't understand it, you simply do it again - neither the customer nor the project manager knows better ... there you are ... there's tons of companies like that out there.