How to avoid being a secretary for engineers (2018)
idratherbewriting.com
idratherbewriting.com
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.
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.
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).
Basically somebody who "solves company's various problems while using computers to do so"
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.
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.
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.
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.
Competence in the sense of intelligence is helpful, and was called for explicitly in your parent comment:
>> ask really good questions along the way
It's basically translating from systems-thinking to chaos ape.
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.
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.
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.
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.
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.
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...
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.
That often requires decent writing skills.
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.
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".
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.
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...
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 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.
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.
The computer is just a way to do it faster.
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.
You clearly haven’t met the right people then.
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.
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.
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.
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.
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
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.
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.
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:
https://documentation.divio.com/
Which has a 30-min presentation:
https://m.youtube.com/watch?v=t4vKPhjcMZg
Prior HN posts on the system are here:
https://hn.algolia.com/?q=https%3A%2F%2Fdocumentation.divio....
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.