I've never understood writing as a specialization without any subject matter knowledge. For example Journalism degrees are often the first step in becoming a writer for a newspaper. The journalist ends up in the 'business' or 'politics' team even with no experience in these fields.
My naive suggestion for improvement would be to develop technical writing skills in addition to another degree or field. Want to write about science? Then do a science degree as well as a writing course.
Same with documenting software. Isn't it better to have knowledge about software when writing documentation? I'm not talking advanced CS here, I mean basics.
I think the article supports my view. The author hit a limit at his workplace because he specialised in writing without a deeper knowledge of what he was writing about. Instead of gaining that knowlege prior to working he had to learn on the job, which is fine but not ideal if it's not necessary.
You could say the same thing about software development... how is it reasonable for engineers to have opinions about specific business/subject-matter requirements, when all we've studied in detail is CS? Want to write quantitative trading software? Get a degree in economics and take a couple coding courses. Want to write an ad platform? Get a degree in marketing, with a minor in auction theory.
Everything in industry - and, increasingly, academia - is interdisciplinary. Given finite time to study, you're going to have to learn one "side" of the job on the job.
> Given finite time to study, you're going to have to learn one "side" of the job on the job.
Way too many programmers focus only on the coding part. I ABSOLUTELY think programmers in general should try to learn the subject-matters they work with much better than they do.
Someone who has above-average competency in programming AND for a business domain, may end up more useful than someone who is within the 20% best programmers, but who relies on having all requirements provided in perfect detail.
Getting to this point from a MSc in CS or a similar field does require some effort. Maybe you can learn some of that on the job or maybe you can attend some courses or other training, or maybe you learn from reading some books in your spare time.
Some things are hard to go back to after you leave college, though, and I think in particular Math is something it pays to pick up early. And with some more math/stats early on, it often becomes easier to pick up the more technical parts of many applied fields (such as data science, marketing, economics, engineering, etc).
Exactly. Even jobs that could be done in earlier times with just pen and paper, tend to require something similar to software to do effiently now.
A domain expert that has even BASIC coding skills can actually by much more useful than one who has none at all, if there exist programming-like environments that enable them to make use of such skills.
Let's say you have two experts in some business domain, and they need to provide input to some data pipeline process.
If one of them can express their input in a format that can actually do the computation needed, let's say in Jupyter or in an ETL tool like Pentaho, you can find ways to operationalize that with low latency using only 1-2 developers even for a large number of such experts.
If the other will only produce requirements in Confluence or Office, and the developers need to decode these requirements and turn them into working code, there are a lot more ways things can go wrong. Often, this requires multiple iterations to iron misunderstandings. This workflow can easily add a need for one extra developer PER domain expert to do the same job, and also take longer to get into production.
In other words, the value generated by the first expert may easily be the same as that of from second expert PLUS the value from one developer, or even more when taking into account that more employees need more managers, more meetings, etc.
Now, what sometimes happens in organizations, is that the first domain expert is not recognized as a super-valuable domain expert, but is instead treated as a below average developer. They may even have such a title, even if in many cases (at least in my experience) their education may be something like economics or marketing, or they may be self-taught.
But when that person leaves, the organization first fills up the role with a new dev, but quickly hits the wall because there are nobody left that understands the business side.
And as the new junior employee spends all of their energy to understand the modern tech stack that most of the Cool Devs are using, managment discovers that the second domain expert suddenly is a bottleneck, while the productivity of the organization has gone down by half or more.
Yes, you could say that about every field, but for some reason people like to apply it to some fields that are viewed as sterile without some other domain knowledge. I think this situation speaks to the relative power of various professions.
Shouldn't accountants for tech companies understand deeply the nature of software development, in order to avoid being bean counters and support innovation properly? Shouldn't doctors know about the professions of their patients, in order to recommend effective lifestyle changes to improve their health? And so on. And yet, no one claims that doctors or accountants are deficient without domain knowledge of other fields.
So I think it's weird to think that software engineers or writers are somehow incomplete unless they also have training in other so called "real" domains. You pick up the domain knowledge naturally as you work on specific projects if you have the needed curiosity to do your work well. Software engineers are masters of their own domain: how abstract information is manipulated, and can apply this skill to any domain when necessary.
> Isn't it better to have knowledge about software when writing documentation? I'm not talking advanced CS here, I mean basics.
I would say that’s probably about as much as you would want. The best technical writer I ever worked with went from basic computer skills to becoming an expert at deploying and configuring the database software we developed on myriad infrastructure. The newcomer’s mindset helped make the writing wonderfully approachable for anyone to read.
The process was always something like: 1) Learn how to do the thing, but ask really good questions along the way (I often reconsidered some of my own design choices from those questions) 2) Use the gathered information to write about doing the thing.
I'd say that when a question from a child is called "stupid", it's more likely that the grown-up is the stupid one.
Children can ask hard questions sometimes, and grown-ups can get embarrassed when they don't know the answer. Instead of admitting their limitations, many adults will call the question "stupid" or the euphemisms "funny" or "strange", indicating that the child should not ask such difficult questions.
Well, there's more than one relevant sense of "competence". Competence in the sense of acquired skills can be harmful to (introductory) tech writing, because experts pay attention to different things than beginners do.
Competence in the sense of intelligence is helpful, and was called for explicitly in your parent comment:
Exactly. The competence is in knowing which questions to ask. That knowledge comes from a deep and intimate understanding as to not only how you (the individual) goes about solving problems, but how human beings in general approach problems. Then add in that you have to know how people (again, in general) react to learning they were wrong, how people make and change habits, etc.
It's basically translating from systems-thinking to chaos ape.
Every time I've seen a journalist report on a topic that I have in-depth knowledge of, the article was misleading and usually flat out wrong. This is even when the journalist has no bias. When the journalist does have a bias, it's just worse.
Over time this has made me suspicious of all reporting by journalists.
The reporting on the 737MAX is a stellar example of this. The only reasonably accurate reporting I've seen on it is by Aviation Week.
Whilst I disagree with getting a whole degree in order to have some authority in the field, I wholeheartedly agree with the message.
I remember a section of the book "The Art of Thinking Clearly" by Frank Dobelli dedicated specifically on that subject. I don't remember the exact quote, but it is something along the lines of:
"We cannot forget that news anchors are nothing more than perfectly coiffed teleprompter readers".
One example that the author brought in the book was how these same TV anchors/news readers types often are invited to moderate debates on subjects they have absolutely no knowledge of.
At some point it becomes a matter of who's available for what, and for what pay. Newspaper jobs and journalism degrees are a match in terms of availability and pay. Likewise programming jobs and CS degrees. If someone gets past the "hump" of learning a lucrative technical field, it's going to be hard to hold them back from going further to the point where they're capable of working in that field.
There's probably (haven't ever checked the numbers) a situation where it's cheaper to pay a technical writer to write documentation than to have a programmer do it.
For that matter there are engineers who are "secretaries for engineers" in the sense that a junior engineer or designer does work for cheaper than what it would cost for a senior engineer to do it. A lot of engineering is like the proverbial iceberg, where 85% of the work is invisible and doesn't need extensive domain knowledge, such as detailing drawings after a senior engineer has done the hard quantitative engineering. I'm one of the domain experts at my workplace, and I do get asked questions related to my expertise, but it doesn't happen all that often.
I got a science degree at a liberal arts college, meaning that I learned enough to do decent technical writing. But going into science writing would have meant a sacrifice in terms of pay and probably job security.
As a programmer with a CS degree who has also dabbled in writing, I can tell that writing well is a lot harder than programming. A good writer can ask the right questions and present them in a way that their target audience can understand. That's the whole point of specialization - programmers should program and journalists should journal. Completing a science degree would be extremely time consuming and wasteful if your goal is to help with science communication.
I think the problem with a lot of technical journalism right now isn't because journalists are lazy or not smart enough to do the research or understand the science. It's because of the insane publishing requirements put on them which leads to subpar quality. Encouraging they get an extra degree won't help fix that.
Hard disagree. The skillsets for writing and programming are largely orthogonal. The fact you're a programmer who finds writing difficult means nothing in regard to the relative difficulty of each skill.
On the contrary, I have always found writing well (Based on what other people have told me) relatively easy without putting in much focused effort. Whereas programming was something I had to put many hours into.
You got more practice writing human languages. You probably started learned to read/write ~4-6 years old and continued learning for more than 10 years. You probably studied in school that took up a significant portion of your time.
Imagine if you spent that time writing code. Starting at that early age. It would feel easy too.
Even a professional software engineer probably reads and writes more in human language than in code. Reading/writing emails, chatting with colleagues on Slack, or reading comments on HN...
That isn't what I mean. Many, many people have very poor writing despite having done it for many years and having studied it in school. My writing has always been good relative to my peers, and I haven't particularly tried to improve it.
> Hard disagree. The skillsets for writing and programming are largely orthogonal. The fact you're a programmer who finds writing difficult means nothing in regard to the relative difficulty of each skill.
How do you survive code reviews with poor writing?
I insist on well-documented code because conveying intent and purpose of code is extremely important.
> As a programmer with a CS degree who has also dabbled in writing, I can tell that writing well is a lot harder than programming.
For you. Others will find the reverse. Specifically those that have been trained in writing and only dabble in programming. Don't assume everybody thinks and feels the same.
Anyway, I think the world would be far better off with less well-written nonsense. Even if it's replaced with badly written good stuff. Or even if it's not replaced at all.
I agree. A science writer should be able to understand the topics they write about well enough to extract the essence.
Way too many science writers just spread misinformation and confusion. This is worse than useless (except perhaps to sell clicks, or perhaps to reinforce partisan dogma), as it contributes to the general public becoming increasingly distrustful of "science".
I agree with both of your points, but I would argue that the blog post is an example of overspecialization. In some roles generalists are better than specialists, and I think technical writing is in this category. Then the question becomes: how to get general knowledge? I think learning on the job is suboptimal for most cases.
And I agree about the resource issues in journalism, but I think this is a secondary issue to the problem of having a fundamental understanding of what you are writing about.
I fully agree: I am a trained journalist and a programmer.
Ten years ago it was possible to feed a family with an editors salary and have a work environment that made for all around decent articles.
But then the public decided they are not going to pay for journalism anymore and that's exactly the reason we are where we are today. Endless SEO-Content-Attacks, a new breaking news headline every 30 minutes and editors that are not "editors" anymore but "content managers" - people who "write articles" for 20 dollars a pop and content creators who have to finance their notebook reviews with affiliate links of said piece of tech - wonder how independent these review are going to be. All the while publishers trying to get ouf of the reds and into the black and trying to appease the almighty Google ad good as possible.
You people brought that onto yourself. Anybody who wants to write for a career today must be able to afford it...
Disagree with blaming the general public. I'm a librarian-programmer who's dabbled in writing and done some political comms work, though never journalism.
You're right about the lack of financial ability for writing to keep one afloat financially (unless you're willing to do sketchy work, of course), but that's more a tragedy of the attention economy commons than the fault of the average news consumer. The business divisions of publications realized they could make as much money without paying their journalists as much; why wouldn't they do that? The answer, of course, is because if every outlet turns into a tabloid that it turns out that's bad for society, but no outlet is going to give up the attention economy/data $$$ in exchange for a healthier society because their competitors are still playing the game and they're not going to disadvantage themselves.
Journalists and publications are also not helping their case with trying to run so leanly (no editors, QA, fact-checking, etc.) that their work is no longer worth paying for for those of us who ARE be willing to pay for decent journalism.
The incentives of both journalists and their bosses no longer match each other, and in addition both sets of incentives also don't match what society requires.
> As a programmer with a CS degree who has also dabbled in writing, I can tell that writing well is a lot harder than programming.
As an award winning writer with a day job in programming writing bad code is easier than writing bad prose. Most people have been exposed to enough good writing to know it when they see it even if they don't appreciate it.
Most programmers have never seen good code. The only person to consistently aim for well written code is Knuth: https://wiki.c2.com/?TexTheProgram
That he needed to invent a whole new ecosystem to do that in should tell you how far away the average programmer is from getting there.
> The only person to consistently aim for well written code is Knuth
That is a ridiculous statement. Are you really saying that from all the developers all over the world you believe that he is the only one who consistently aims for well written code? How would you even start ascertaining the truthfullness of this? Have you went around, interviewed all the developers and found their ”aim for well written code” to be lacking in consistency?
> That he needed to invent a whole new ecosystem to do that in should tell you how far away the average programmer is from getting there.
That he thought he needed to invent a new ecosystem tells you much about him, yes. It absolutely does not tell you about the aims of others. Perhaps others found that they can write well writen code consistently even without inventing a new ecosystem.
That is a content free statement, you should think better.
>Are you really saying that from all the developers all over the world you believe that he is the only one who consistently aims for well written code?
Pretty much. The only people who write code for people instead of computers are those who use literate programming. There are a few of them around - the largest project being axiom: http://www.axiom-developer.org/ - but they are basically a rounding error.
>How would you even start ascertaining the truthfullness of this? Have you went around, interviewed all the developers and found their ”aim for well written code” to be lacking in consistency?
Every project I've looked at, including those praised for great code quality, were universally terrible. People seem to think that code quality means using consistent variable names and indenting. Which is like thinking that the reason why War and Peace is a good novel was because of Leo Tolstoy's neat handwriting.
>That he thought he needed to invent a new ecosystem tells you much about him, yes. It absolutely does not tell you about the aims of others. Perhaps others found that they can write well writen code consistently even without inventing a new ecosystem.
It tells me that no one else has ever thought about the point of code. It's not to get a computer to do something. It's to explain to people how to do something.
> That is a content free statement, you should think better.
It is the thesis statement of my comment. It tells you what I think of your opinion while the rest of them tells you why.
> Every project I've looked at,
Great. So what? That might be enough to show that many projects are terrible. It doesn’t show what those people’s aim was. And certainly not enough to show that nobody other than Knuth consistently aims to write well writen code.
On the contrary it is super simple to prove you wrong. I have multiple excelent colleagues and former colleauges who are obsessed about writing well written, readable code. They work hard to find the right abstractions, document their designs, discuss the macro and micro level consequences of choices they make. They worry about creating missuse resistant APIs, and rewrite code when they deem it not simple and obvious enough. They review fellow developers code to maintain these high standards. These are all forms of consistently aiming to write well written code.
When you say “only Knuth…” you are dissing all of these great engineers. And you are dissing them, without even knowing them.
> People seem to think that code quality means using consistent variable names and indenting.
Technical Writing is very different than other forms of writing.
Journalism is 'real world research' - the end result is some writing.
Technical Writing is usually mostly just the end result part.
Journalists 'research', technical writers 'form the right phrases'.
It definitely helps to have domain knowledge but you don't need a degree in anything.
Someone to write comprehensive docs - that's another story. You almost want an Engineer who is a 'good explainer', and then finished off by the technical writer who can clean it all up and help edit.
I believe that the author mistook "able to write interesting stuff" with "good at technical writing". I mean the blog was a kinda fun read. But it demonstrated none of the expository skills that I'd want for documentation.
At our organization we have a nontechnical sprint tester that executes manual tests and creates customer facing documentation. This sprint tester is part of our pull request approvals on our new feature branch builds.
The engineers write the unit tests, integration tests and create the initial draft of a manually executed (zephyr) test.
The sprint tester enhances the manual test and also creates the customer facing documentation/training content. What’s been nice about this is if the sprint tester finds its overly complicated to explain a new feature they can provide feedback about the design before it gets merged into the production builds. In this way they’re not just documenting what’s been done, but are contributing to the design.
Teams that really deliver well pull folks that work in supporting roles into the engineering & product team culture. Transactional relationships hit limits depressingly quickly - they also become toxic in ways that hurt the product you're trying to build.
If you treat your supports as equal team members you can attract and retain amazing talent that helps you iterate and deliver good products quickly. If you throw tasks over the wall and let people indulge in power fantasies you're wasting your time.
>pull folks that work in supporting roles into the engineering & product team culture.
This can be one of the good ways to get something like a team of 10 (consisting of 5 engineers and 5 non-engineers), to outperform 10 engineers in a culture where they have much less integration with the non-engineering employees.
Some projects are based on a (big?) complex idea of a single outstanding specialized engineer.
If the project or prototype is to be advanced or completed single-handedly, it's essential for that engineer to have enough knowledge & ability, often without very many notes and data, so they could halt the project at any time, then fully produce as detailed documentation as necessary only after the engineering itself is over. At least for that particular milestone. That would be the only time it was finally no longer a moving target.
From that point with hindsight, depending on the degree of thoroughness needed, that top engineer can then justify a period of non-progress while they sit down and focus on fully appropriate documentation for that exact completed or halted project. That would be an engineer who was expected to be an accomplished technical writer already beforehand.
With the knowledge of what this kind of final thorough documentation would look like the whole time, since even before the project got underway, the interim note-taking and essential micro-subdocumentation tasks could be anywhere from truly minimal to almost-publishable as you go along. Depends on how the engineering process is slowed by having the engineer spend more time sitting down producing interim documentation, when real progress might be completely dependent on them not sitting down. Whether or not they are actually running around designing, building, or testing "engines" the entire time they are not remaining seated.
Not every kind of engine is needed for a rocket, but every kind of rocket needs an engine.
But you don't get to the moon single-handedly.
The reason a team is then often formed can be because one engineer is simply not enough for the size of the project, or it can greatly expedite the completion of subengineering components.
The reason to have a dedicated writer is the same reason to have a team to begin with.
For a multi-year project, if you're going to document it thoroughly, the top writer will be working closely with the top engineer for quite a while. Take advantage of that time so a lot of learning takes place in both directions.
Nothing else comes close.
Now there are times when the top writer needs to be the second engineer, so the top engineer can focus only on the engines themselves, and it needs to be accepted that a very capable second engineer will be focused intensively on documentation rather than engines of their own for that period. Ideally final editorial review can be made by an accomplshed technical journalist without the need for the editor to be very familir with that exact engineering discipline. This does require that the second engineer rise to a certain level of journalistic sophistication, probably best if an entire engineering culture can do it.
Very few things are ideal.
In another part of the spectrum, every engineer may have more than one engine and there's no way that's going to be thoroughly documented no matter what. Even if each engineer had their own professional journalist, if the engineers are being streched thin so is the documentation.
This is where the technical writer can feel like a bewildered scribe.
And everything in between.
So I really admire the author's actions to step up to the plate to handle the more difficult situations by improving their actual engineering familiarities & abilities as journalists.
If the top writer is going to be a professional journalist instead of the second engineer, the writer still needs to spend a great deal of time along with the second engineer in the room with the engine. And fundamental questions from the writer need to be answered to good journalistic satisfaction as documentation goes along. If the witer can not be recognized as one of the essential engineering team members in this case, you're not getting your money's worth.
Like it says in the article, it's more than just documentation, it's communication.
And with so many projects the only thing you have to show for it afterward is the paperwork.
So engineers need to step up to the plate to do their share to make better documentation possible to begin with.
As much as I appreciate a well turned phrase, I am highly suspicious about reading documentation written by someone who doesn’t fundamentally understand the topic.
I find tech writing skill to be necessary but not sufficient to competent at technical writing. GPT-3 is more than sufficient if my goal is phrases that sound reasonable may or may not capture the essential concepts
The primary author of the text must understand what is to be communicated AT LEAST as well as the target audience. If you are supposed to write a user manual for the next iPhone, the main trick is not technical, but rather to figure out of to structure relatively simple information in a way that even your mother can understand.
Still, it's probably a good idea to have an engineer go over the text after, to make sure there are no glaring errors.
If on, the other hand, you write documentation for Apache Spark, you probably need to be a pretty competent computer scientist, data engineer or data scientist. Maybe a tech writer can go over the text after, but they will probably not be able to understand the content, so can do little beyond formatting, language and structure (and even that needs to be reviewed by a real tech person after).
In the latter case, it may be VERY useful for the tech person to have some formal training in technical writing, in addition to be the kind of engineer that is also pretty good with language and presentation.
> I am highly suspicious about reading documentation written by someone who doesn’t fundamentally understand the topic.
It really depends on who the target audience is.
If we are writing for other engineers on the inner workings then yes maybe an engineer from within the team will probably be better suited.
However, if it is a technical file for an external audience or regulatory work I would much rather have an experienced 'Analyst' or 'Systems Eng' (in the requirements sense of the title not sys eng in the US infrastructure sense of the word) do the write up.
We as technical people vastly underestimate how crap we are at explaining things to someone without the very problem-specific domain knowledge.
It would be interesting if the Author instead turned in a less-effort, sloppier documentation that just stuck to the haphazard bullet points, to provide contrast to their optimized work. The issue with making complex things simple is just that - it looks so simple.
Engineers are rarely good at writing technical documentation, especially compared to technical writers (that is “secretaries” per author’s lingo) which by definition, should be. Engineers generally cost more than technical writers. Good technical writing saves engineering time both during AND after the documentation is produced.
Author spends large amount of time, to poorly express that to be a good technical writer, you must understand who needs what and why, then figure out how to solve that the best way based on the context.
____System for to Producing Tech Docs____
Anyone looking for a good system of producing documentation should check out:
I was joking with my boss the other day that the way I start out my technical writing (which I hate because it is such a different skill set) is to start “talking shit” and then I self-edit based on the fear that someone is going to call me out for this or that, and then I have my boss look at it and edit it before it goes anywhere.
It’s my new framing of it because I think that storytelling is fundamental to producing useful information. Also, I was a drama major w/ comp sci minor, so I’m probably doing what I was meant to.
Technical writing should evoke emotions, not at 6 or above in a 1-10 scale of intensity, but shit, say something or what’s the point? There’s always drama at work with enough people, always politics. Sprinkling a bit of that is actually healthy imho. Not that you want cringe, but the tone, it’s colored different, when you are describing why port numbers were chosen, for example. Tell people stories.
Also, be willing to invite someone else to shape and change even the things you feel the most conviction about. Too often we put ourselves into a cultural prison where we insist on making measurable contributions like an API or some cool feature that we can “specialize” in. Specialize on your own time, that’s my advice. At work, do something special, don’t specialize. It’s a myth.
My naive suggestion for improvement would be to develop technical writing skills in addition to another degree or field. Want to write about science? Then do a science degree as well as a writing course.
Same with documenting software. Isn't it better to have knowledge about software when writing documentation? I'm not talking advanced CS here, I mean basics.
I think the article supports my view. The author hit a limit at his workplace because he specialised in writing without a deeper knowledge of what he was writing about. Instead of gaining that knowlege prior to working he had to learn on the job, which is fine but not ideal if it's not necessary.