61–70 of 138 posts
Any other engineers trying to improve their writing skills? Any additional resources or tips to help me refine my drafting and editing process?
Earlier quoted context omitted.
A glossary is the most important document ANY project should have and maintain. Everything else is secondary.
Nah, it doesn't pass the sniff test. Is it more important than a list of critical bugs? A document explaining how a developer can get the application up and running? A document detailing how the production server is setup and how to gain access? When you think about it, lots and lots of projects manage without any kind of glossary but would go up in flames without some kinds of documents.
Earlier quoted context omitted.
If it's a kind that existed generally, then we can have a past tense. "He laughed with the kind of booming abandon that made the whole restaurant turn around and look, in the before-times."
We can describe "a kind that exists generally" even if the restaurant turned and looked (then) and would still turn (now and in the future). Just need to change "the" with "a": > He laughed with the kind of booming abandon that made the whole restaurant turn around and look. to: > He laughed with a kind of booming abandon that made the whole restaurant turn around and look. In this case his laugh is still described a…
>One of the best writing tips I've ever gotten was to avoid using demonstrative pronouns. Instead of saying “this” or “that,” you should add a noun to spell out exactly what you’re referring to, even if you’ve just mentioned it. This piece of advice is maybe the only thing I remember from my college English class. A naked "this" or "that" now feels shamefully lazy to me.
Totally agree! The worst example is a paragraph that starts with ‘this’. The author might remember what ‘this’ means at the time of writing, but other readers have to then insert themselves into the author’s stream of consciousness. ‘This’ paragraphs also make no sense when extracted from the main report, or to readers who are dipping in and out
All great advice. Except for “avoid passive”. It’s a part of the toolbox that changes the perspective on an action. “The pull request got merged” vs. “The maintainer merged the pull request”. If i want to talk about the new feature that gets implemented by the pull request, then I mislead the reader by emphasizing the maintainer, rather than the pull request. The passive also allows you to choose whether you want to…
If you must use passive in situations like these, please at least identify the agent, e.g. "X will be done by Y". Oy just use the shorter, explicit alternative: " X will do Y"
> You’ve heard this advice before. But you should understand why you shouldn’t use passive voice in your writing. It’s not just “bad style.” The ususal misunderstanding that everyone repeats. Read Williams‘, Clarity and Grace, or watch McEnerny‘s lecture on YouTube. Passive has its use, and it‘s not "to obscure who is doing the bad thing".
The purchase order has been made.
Your virtual machine has been created.
I see this a lot in corporate environments, and it's by low level managers thinking every bit of information they're trusted with is so delicate and confidential, they must go above and beyond to reveal the least possible amount of it. Note, in the examples above, it was the manager themselves doing the action. What's wrong with "I did this", "I did that"? This is LARPing as CIA agents (or whatever), and they like the sound of it (I want you to know I have information I can't share, you little shit!).
"I've just created your virtual machine" peasant
"Your virtual machine has been created" special ops elite force management
Mind you, 99.999% of the time, the concealment of "who did the thing" is totally unnecessary. It's only there to reinforce status.
I found myself writing a book recently, completely left field to my normal technical work. I'm intending on approaching a literary agent but I need it reviewed first and I'm looking for dispassionate, distanced, but informed opinions.
One of my pet peeves while reading technical documents is coming across acronyms that have not been introduced to the reader yet. When this happens over and over again across several documents of a project and people working on the project change over years, sometimes we end up in a situation where nobody can tell anymore what a particular acronym expands to. In fact, more than once, I have seen the bizarre situation…
A glossary is the most important document ANY project should have and maintain. Everything else is secondary.
One of my pet peeves while reading technical documents is coming across acronyms that have not been introduced to the reader yet. When this happens over and over again across several documents of a project and people working on the project change over years, sometimes we end up in a situation where nobody can tell anymore what a particular acronym expands to. In fact, more than once, I have seen the bizarre situation…
One of my pet peeves while reading technical documents is coming across acronyms that have not been introduced to the reader yet. When this happens over and over again across several documents of a project and people working on the project change over years, sometimes we end up in a situation where nobody can tell anymore what a particular acronym expands to. In fact, more than once, I have seen the bizarre situation…
Even better:
Get" rel="nofollow">https://dsc.prod.ex.com/gettoken">Get an access token from the Data Management Console (DMC) to access the Customer Data Indexing Service (CDIS).
The best documentation is no documentation. This documentation is there because the two systems aren't linked and that is the real issue. If there isn't budget to do the integration, then better is have the hyperlink to DMC on the log in page of the CDIS, which can then avoid the separate documentation altogether.