3 ms·

I don't think I trust the whole idea of "technical writers". Software is a complex thing. Is was recently pouring through docs of Kubernetes and Spinnaker, and

I don't think I trust the whole idea of "technical writers". Software is a complex thing. Is was recently pouring through docs of Kubernetes and Spinnaker, and with the minutia of one-off, OS specific warnings and use-cases, strange naming conventions, gotchas, and conceptual jargon, I find it really terrifying that somone who's only a "technical writer" would be writing the published documentation of such things. How do they know they're correct? Have they run the tests? Docs are hard enough to read as they are, and often, you're reading them over and over again because there's some detail that you've missed for your use case, and these are generally details possibly known only by the issue reporter or someone who actually implemented the thing. Docs aren't hard to write, and if you have to, you should just copy paste them from your comments and/or unit tests (unless you haven't written any of course). Making docs pretty and easy to write by someone else because you're too lazy too is an even bigger sin IMO. That's all I have to say about that.

DrScump 8y ago
How do they know they're correct? That's the whole point of having project team members (R&D, QA if a distinct organization, product management, and, ideally, Support) participate in the review process. You need someone who can write, follow (or prepare) a style guide for a consistent motif across products, and understand what the customer needs in a document. It's not their job to understand all the minutiae in a product -- that's what the broader team is for. A great tech writer is a treasure, and that person will treasure diligent reviewers. One I worked with later became a published author of historical novels.
- abathur 8y ago
  I think this is the big thing the previous poster is missing. The technical writer isn't going to go out in the wilderness with a copy of the source, assume they understand it after reading it once, write the documentation, and hit publish. Broadly, good writing (even poetry, fiction, and creative non-fiction) has a deceptive amount of research involved. One of the subtle skills of a good writer is knowing what they don't know, and knowing how to fill the gap. Whether they're flagging things they don't understand as they go and resolving them in bulk, or regularly checking their understanding with maintainers as they encounter problems, a good technical writer isn't going to just pretend they understand.
dtech 8y ago
> Docs aren't hard to write I disagree, I've seen some terrible docs on otherwise good software. Furthermore developers usually are not that interested in creating (user) documentation. In your whole spiel could "technical writer" could be replaced by "customer service", "UX designer", "system administrator" or any number of software-related tasks/jobs. Theoretically they could all be done by software developers, but as some point you'll need to split responsibility if you want to work with more people and writing documentation is as good a split point as any.
tasuki 8y ago
> I find it really terrifying that somone who's only a "technical writer" would be writing the published documentation of such things Why? Are you suggesting that technical writers don't have enough understanding? Good technical writers have a thorough understanding of the product they're documenting. An ex colleague of me switched from being a software developer to a technical writer. He very much understands things from a software developer perspective. As a software dev, I'll take docs written by a technical writer over docs written by a software dev: - Writers can organize the docs better, will avoid wall-of-text rambling. - Writers can write (they eg know the difference between "pouring" and "poring").
- wenc 8y ago
  Another advantage: Technical writers write from the perspective of users. Devs are sometimes too close to the code (too much scaffolding and presumptions) to understand what the user’s experience and thought processes are like. Technical writers can bridge that. Writing as a process also helps expose gaps in thinking — in this case, in the user facing implementation. This feedback can in turn be useful for devs. One example of where technical writing can help is PySpark. Because Spark is JVM centric, it can be relatively difficult for Pythonistas to get started with unless one already knew how things were laid out. I had to read multiple tutorials to set things up the right way before “import pyspark” would even work. Not to diminish the tremendous amount of efffort that has gone in the Spark docs, but that is one area where a good technical writer could add a lot of value. Side note: “findspark”, for the trivially simple package that it is, simplified getting up and running with PySpark. But I had to find out about it through a random tutorial.
alxlaz 8y ago
> Docs aren't hard to write, and if you have to, you should just copy paste them from your comments and/or unit tests (unless you haven't written any of course). I've seen some companies doing that (worse, I've seen them doing it with their programmers' reference guides -- not for libraries, but for hardware devices). The result is nothing short of catastrophic. They are, by far, the worst and least usable docs I've ever read. They are so mind-bogglingly bad that it would probably be better if they didn't publish them at all, and just made it easier to get a hold of sample code for their development boards. I don't know if dedicated technical writers with no technical experience are the way to go, and I am more partial to paying big bucks to software developers who also know how to write well, but I might be a little biased here :-). But coming from a "docs aren't hard to write" perspective is a really bad idea. Good documentation is extremely hard to write (anecdotally, if I'm covering a complex topic, it sometimes takes me more time to figure out which terms to introduce and in what order than it takes me to actually write the damn thing). Once you know the language, writing stuff that computers understand is orders of magnitude easier than writing stuff that people understand well -- unlike people, computers work the same way, and many instances of unclear language are also syntax errors, so there's less potential for disastrously misunderstanding things. (Sauce: many lifetimes ago, I used to work for a computer magazine, the printed kind, so I'm the one who always gets sent to confer with the tech writers, I write "getting started" guides for new colleagues and so on.)

DrScump 8y ago

How do they know they're correct? That's the whole point of having project team members (R&D, QA if a distinct organization, product management, and, ideally, Support) participate in the review process. You need someone who can write, follow (or prepare) a style guide for a consistent motif across products, and understand what the customer needs in a document. It's not their job to understand all the minutiae in a product -- that's what the broader team is for. A great tech writer is a treasure, and that person will treasure diligent reviewers. One I worked with later became a published author of historical novels.

abathur 8y ago
I think this is the big thing the previous poster is missing. The technical writer isn't going to go out in the wilderness with a copy of the source, assume they understand it after reading it once, write the documentation, and hit publish. Broadly, good writing (even poetry, fiction, and creative non-fiction) has a deceptive amount of research involved. One of the subtle skills of a good writer is knowing what they don't know, and knowing how to fill the gap. Whether they're flagging things they don't understand as they go and resolving them in bulk, or regularly checking their understanding with maintainers as they encounter problems, a good technical writer isn't going to just pretend they understand.

dtech 8y ago

> Docs aren't hard to write I disagree, I've seen some terrible docs on otherwise good software. Furthermore developers usually are not that interested in creating (user) documentation. In your whole spiel could "technical writer" could be replaced by "customer service", "UX designer", "system administrator" or any number of software-related tasks/jobs. Theoretically they could all be done by software developers, but as some point you'll need to split responsibility if you want to work with more people and writing documentation is as good a split point as any.

tasuki 8y ago

> I find it really terrifying that somone who's only a "technical writer" would be writing the published documentation of such things Why? Are you suggesting that technical writers don't have enough understanding? Good technical writers have a thorough understanding of the product they're documenting. An ex colleague of me switched from being a software developer to a technical writer. He very much understands things from a software developer perspective. As a software dev, I'll take docs written by a technical writer over docs written by a software dev: - Writers can organize the docs better, will avoid wall-of-text rambling. - Writers can write (they eg know the difference between "pouring" and "poring").

wenc 8y ago
Another advantage: Technical writers write from the perspective of users. Devs are sometimes too close to the code (too much scaffolding and presumptions) to understand what the user’s experience and thought processes are like. Technical writers can bridge that. Writing as a process also helps expose gaps in thinking — in this case, in the user facing implementation. This feedback can in turn be useful for devs. One example of where technical writing can help is PySpark. Because Spark is JVM centric, it can be relatively difficult for Pythonistas to get started with unless one already knew how things were laid out. I had to read multiple tutorials to set things up the right way before “import pyspark” would even work. Not to diminish the tremendous amount of efffort that has gone in the Spark docs, but that is one area where a good technical writer could add a lot of value. Side note: “findspark”, for the trivially simple package that it is, simplified getting up and running with PySpark. But I had to find out about it through a random tutorial.

alxlaz 8y ago

> Docs aren't hard to write, and if you have to, you should just copy paste them from your comments and/or unit tests (unless you haven't written any of course). I've seen some companies doing that (worse, I've seen them doing it with their programmers' reference guides -- not for libraries, but for hardware devices). The result is nothing short of catastrophic. They are, by far, the worst and least usable docs I've ever read. They are so mind-bogglingly bad that it would probably be better if they didn't publish them at all, and just made it easier to get a hold of sample code for their development boards. I don't know if dedicated technical writers with no technical experience are the way to go, and I am more partial to paying big bucks to software developers who also know how to write well, but I might be a little biased here :-). But coming from a "docs aren't hard to write" perspective is a really bad idea. Good documentation is extremely hard to write (anecdotally, if I'm covering a complex topic, it sometimes takes me more time to figure out which terms to introduce and in what order than it takes me to actually write the damn thing). Once you know the language, writing stuff that computers understand is orders of magnitude easier than writing stuff that people understand well -- unlike people, computers work the same way, and many instances of unclear language are also syntax errors, so there's less potential for disastrously misunderstanding things. (Sauce: many lifetimes ago, I used to work for a computer magazine, the printed kind, so I'm the one who always gets sent to confer with the tech writers, I write "getting started" guides for new colleagues and so on.)