[HN Gopher] What I think about when I edit (2019)
___________________________________________________________________
What I think about when I edit (2019)
Author : tarf
Score : 258 points
Date : 2024-04-06 07:48 UTC (15 hours ago)
(HTM) web link (evaparish.com)
(TXT) w3m dump (evaparish.com)
| tosh wrote:
| > Don't use adverbs
| richrichie wrote:
| Indeed!
| hubraumhugo wrote:
| Any other engineers trying to improve their writing skills? Any
| additional resources or tips to help me refine my drafting and
| editing process?
| thangalin wrote:
| Anything by Diana C. Reep. Technical Writing: Principles,
| Strategies, and Readings is particularly insightful:
|
| https://www.amazon.ca/dp/0205721508
| spit2wind wrote:
| Strunk & White is always good to thumb through:
| https://archive.org/details/TheElementsOfStyle4thEdition The
| Wikipedia has links to other copies, like on Project Gutenberg.
| MrVandemar wrote:
| Death Sentence - The Decay of Public Language, by Don Watson.
|
| Blisteringly good. Not aimed at technical writers, but
| encourages you to think about how to really use language
| effectively and robustly.
| lawn wrote:
| I've been trying to improve by making a conscious effort to
| practice it. I've been trying to blog and even wrote a book,
| partly to increase my writing skills.
|
| The book that helped me the most is On Writing Well: The
| Classic Guide to Writing Nonfiction.
|
| I also wrote a blog post about some of the lessons I learned:
|
| https://www.jonashietala.se/blog/2023/11/25/writing_lessons_...
| RheingoldRiver wrote:
| Developing Quality Technical Information -
| https://www.amazon.com/Developing-Quality-Technical-Informat...
|
| My review + some notes - https://river.me/blog/book-review-
| quality-technical-informat... (it's very good)
| ndand wrote:
| Google has a few courses about technical writing for engineers:
|
| https://developers.google.com/tech-writing
| beezlebroxxxxxx wrote:
| There are innumerable sources online for improving technical
| writing and they all generally repeat the same conventions and
| "rules". I tend to warn people, though, that over fixating on
| technical writing will not make you a great writer but just a
| capable technical writer.
|
| If you're looking to improve your writing _in general_ , then I
| think Joseph Williams' "Style: Towards Clarity and Grace" is
| the single best book on the subject written so far. Rather than
| simply state certain "rules", it methodically workshops
| examples to show how you can write and rewrite a sentence to
| change your meaning and emphasis at will.
| richrichie wrote:
| I can't recommend Strunk and White's Elements of Style enough.
| probably_wrong wrote:
| Not a source, but rather an exercise: give yourself a tight
| word count and rework your essay until it fits. When one third
| of your article _has_ to go, you start looking really deep into
| how to extract as much value as possible out of every word.
| remoquete wrote:
| Eva is a fellow technical writer. I'm glad to see tech writers
| get visibility in here.
| dijksterhuis wrote:
| > Whitespace is key for technical documentation but can also be
| used to great effect in blog posts, emails, and elsewhere. It's
| hard for people to read long paragraphs, especially on a computer
| screen. They will zone out.
|
| 100%. The explanation (?) I first heard which helped me 'get'
| this whitespace principle was along the lines of
|
| > Have you reached a page in a book with no paragraph breaks and
| thought 'oh no'?
| avg_dev wrote:
| You know, I kind of feel this way about code too. Sometimes
| people don't put in a lot of blank lines to break things up and
| I find that a little harder to read and a bit more intimidating
| than reading with a few blank lines between concepts/actions.
| In fact, I was thinking after I read the article, maybe many of
| these principles apply to writing maintainable code too.
| KineticLensman wrote:
| I was a doc reviewer in my corporate past life and found myself
| using many of these guidelines. I'd add one more: don't use
| different names for the same thing. Many of the docs I reviewed
| had multiple authors and quite often they used slightly different
| terminology. This really complicated things for readers. I
| eventually realised there was a meta-principle here: in tech
| writing, the reader should never have to resolve ambiguity
| created by the authors.
| berkes wrote:
| This gets even worse in software code. When "Naming things" is
| hard, and two people name the same thing, they'll very likely
| give it a different name. A guarantee to maintenance
| nightmares.
|
| DDD by Eric Evans suggests using Ubiquitous Language. Even when
| I don't use anything from DDD, I always add a dictionary.md in
| which we write down the domain terms. What is a Customer? What
| does a "Loan Application" mean. What can we do to a loan
| application and how do we call those actions?
|
| It's one of the easiest tricks, that dictionary.md, but with
| great effect.
| valenterry wrote:
| Why not put those definitions into the code, next to the
| types that define those entities?
| medstrom wrote:
| Your term may not map cleanly to a single OOP class, and it
| may also be used in other function/variable names. There's
| also how you will express yourself in the code comments.
|
| I mean, I'm guessing the dictionary is not just for nouns,
| but also verbs and adverbs. What will "transact" usually
| mean in this codebase? What will "safely" mean?
| ffsm8 wrote:
| > _Your term may not map cleanly to a single OOP class_
|
| That's not really an argument, as it will map to either
| entities or functions, both of which can be annotated
| with this information.
|
| An argument against documenting it on the entities and
| functions would be that this would spread the information
| across the repository. The value you get from doing this
| in a single markdown file is the overview it provides, I
| think.
|
| These kinds of methodologies enable development with high
| turnover in large enterprise, which treat developers more
| like cogs that temporarily work on a given software. And
| if it's just a comment on a file, it'll likely not even
| be seen
| coldtea wrote:
| > _That 's not really an argument, as it will map to
| either entities or functions, both of which can be
| annotated with this information._
|
| No, it might not map to entities or functions. It could
| refer to concepts about the project that are not mapped
| in the code, but are still important to communicate with
| the team, the customers, and so on.
|
| And even for terms that do map to entities and functions,
| it would be a bad idea to have the developers (and
| especially non developrs) hunt them around (even if it's
| just a grep away). As you say, the overview is important.
|
| > _These kinds of methodologies enable development with
| high turnover in large enterprise, which treat developers
| more like cogs that temporarily work on a given
| software._
|
| Even small teams of 4-10 people can benefit from shared
| common terminology, especially if each might work in
| different repos (or e.g. backend and front-end).
| coldtea wrote:
| - Not all project-related terms map to types
|
| - The "types that define those entities" (that do map) can
| be scaterred across multiple source code files (so this
| would also scatter the definitions)
|
| - The code is not where people look for reference, even
| more so for non-coders that still need to refer to the same
| things (e.g. UX, sales)
|
| - The definitions that do map to types, could still be
| reusable in multiple code projects. Putting them in the
| code means you need to repeat them, make sure they're
| consistent, and sync them across codebases when some
| definition is changed/improved.
|
| -
| valenterry wrote:
| The last 3 points make a lot of sense.
|
| The first one however I don't understand. Do you mind to
| give one or two concrete examples of that?
| coldtea wrote:
| > _The first one however I don 't understand. Do you mind
| to give one or two concrete examples of that?_
|
| Not everything about a project maps to a type.
|
| The team might have to handle the issue (and have a way
| to talk about the problem) of back-pressure for example.
| Doesn't mean there's a back-pressure type in the server
| code, or a "back-pressure-handler" class or something
| like that.
|
| And that's still a term referring to a core tech aspect.
| There are terms related to projects that teams need to
| agree on that are appplicable to the sales or marketing
| or user documentation of the software, and not classes.
| berkes wrote:
| For a large part, this can work. But there are several
| cases where it doesn't. Modules, subdirectories, a group of
| classes, etc. Too often, at least a part of the terms don't
| have a logical place to go in code. I consider it worse to
| have them partly here and partly there, than to have them
| all together.
|
| But, indeed, I often repeat the definition or naming in the
| class documentation, module file, methods etc. Knowing
| fully well it will drift, but accepting it does. And
| everyone knows the canonical place is dictionary.md, inline
| docs are merely reminders or copies of that canonical
| place.
| zelphirkalt wrote:
| I tried to introduce that, but few if any people stuck to it
| and still they came up with their own words and different
| understanding of the words that were already in the glossary
| I had created. It felt like they did not care much.
| berkes wrote:
| > It felt like they did not care much.
|
| If software people don't care about using the business-
| domain-language, I think they are very bad software
| developers. The main task of software developers is to be
| the bridge between the domain and computers.
|
| I've met and seen my share of teams that don't want to be
| that bridge, or offload it to "product owners" or
| "managers". They are -without exception- abysmal projects,
| terrible products and quite often have a poor UX. I refuse
| to call these people software developers, instead I refer
| to them as code-monkeys. And with all the generative AI
| going on, these are the first to be replaced by robots in
| our fields.
| Adverblessly wrote:
| Indeed a very important tip.
|
| I'd also add that repeated ideas should be parallel, most
| commonly when you have multiple list items they should be
| presented "similarly", e.g. BAD: Windows is a
| bad operating system for many reasons: * It is ugly
| * Unstable BETTER: Windows is a bad operating system for
| many reasons: * It is ugly * It is unstable
| OR: Windows is a bad operating system for many reasons: *
| Ugly * Unstable
|
| Another problem I often see is documents or presentations that
| don't have a coherent narrative, where the ideas presented feel
| disjointed or random. As much as possible, each sentence should
| clearly lead to the next one and have a clear relation to it.
| Each idea should clearly lead to the next one and have a clear
| relation to it. Where things don't feel related, make sure to
| explain how they are related.
|
| As a simplified example (since this is hard to explain), when
| talking about a new service you intend to introduce you may
| talk about things like plans for scalability, reliability,
| error handling and cost. If you just talk about these things
| with no relevant introduction, they will feel random, but if
| you introduce them ahead of time with an overview of the
| relevant considerations they will feel more grounded.
| Additionally, you may want to discuss cost after scalability
| since the ideas follow from each other (maybe even
| scalability->reliability->cost to explain what we can do for
| reliability at different scales, and then finally the cost for
| each scale and threshold of reliability), whereas error
| handling is usually a technical decision that you may want to
| separate out to a separate discussion.
| layer8 wrote:
| "Ugly" and "unstable" are not reasons, "ugliness" and
| "instability" are. You're also not helping your argument by
| choosing such a derogatory example.
| layer8 wrote:
| Another problem is semantic drift. It often happens that the
| thing that is named drifts in scope over time, but the name
| remains. Sometimes the name becomes just subtly mismatched,
| sometimes the relation to the original concept becomes
| completely lost. It's useful for documentation to recognize
| this and explain the provenance of the name, because otherwise
| the mismatch is prone to cause confusion, irritation, or
| misunderstandings.
| cookie_monsta wrote:
| It's amazing that much of this has to be said, but here's a
| related piece of advice: don't use the same term for different
| things, especially if they're related.
|
| I got a document the other day that described a category which
| consisted of 3 subcategories, one of which had the exact same
| name as the category it belonged to.
|
| I felt like I had slipped into another dimension.
| euroderf wrote:
| > don't use different names for the same thing.
|
| But if there ARE different names, call it out in the
| introduction, and state which one you will be using.
| vundercind wrote:
| Huge vendors make this mistake across their entire system. Like
| data bricks with Workflows and Jobs (same thing). Super
| irritating, friggin' pick one.
| jmmcd wrote:
| I love this.
|
| Inevitably I want to make some improvements.
|
| > "He laughed with the kind of booming abandon that made the
| whole restaurant turn around and look."
|
| The _kind of_? If it 's a kind that exists generically then we
| can't have a past tense, so:
|
| "He laughed with the kind of booming abandon that *makes* the
| whole restaurant turn around and look."
|
| But really, why emphasise it being generic? This is better:
|
| "He laughed with *a* booming abandon that made the whole
| restaurant turn around and look."
|
| ---
|
| > Use lists where relevant, because it's easier to read a
| bulleted list of items than to read a paragraph with the same
| information.
|
| Use lists only where all the items have the same status, in some
| sense. An ordinary paragraph can't be broken up into bullet
| points.
| wizzwizz4 wrote:
| 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."
| jmmcd wrote:
| We now live in a sad, post-apocalyptic world, with no
| booming, no abandon, no turning around, and very few people
| in restaurants.
| coldtea wrote:
| This is hardly a bad description of the current state of
| affairs.
| coldtea wrote:
| 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 as having a
| generalized "booming abandon", but the reaction of the
| patrons isn't a necessary reaction to that "kind of"
| laughter, but to that particular instance of it.
|
| That is, the noun is "the kind of booming abandon" and not
| "the kind of booming abandon that made the whole restaurant
| turn around and look".
| jmmcd wrote:
| This is the best version.
| hovering_nox wrote:
| > "He laughed with _a_ booming abandon that made the whole
| restaurant turn around and look."
|
| Don't the people in the restaurant actually turn around in this
| sentence, whereas they didn't in the original, because it's
| just describing a kind of loudness with an example?
|
| > "He laughed with the kind of booming abandon that makes the
| whole restaurant turn around and look."
| jmmcd wrote:
| > Don't the people in the restaurant actually turn around in
| this sentence, whereas they didn't in the original
|
| No, the original said "made", so I think they actually turned
| around.
| bregma wrote:
| Well, yes, but one is telling and one is showing. A good
| story teller shows and not tells.
| coldtea wrote:
| That's just a literary superstition, similar to absolutes
| we tell kids such as "you should never lie" (that in real
| life are never that clear cut).
|
| A good story teller can both show and tell, depending on
| whatever fits the story, their stylistic choice, and their
| intention.
| amenhotep wrote:
| Maybe he often visited that restaurant and laughed with booming
| abandon and no longer does :) there was, over a specific
| period, a specific kind of booming abandon, justifying "the" -
| but there no longer is, justifying "made".
| coldtea wrote:
| > _The kind of? If it 's a kind that exists generically then we
| can't have a past tense_
|
| It still applies if the past tense is only meant to apply to
| the reaction to what he did at that point in the past ("made
| the whole restaurant turn around and look") and not to the
| general reaction to such booming abandon.
|
| Then this:
|
| > "He laughed with the kind of booming abandon that made the
| whole restaurant turn around and look."
|
| Can still refer to the generalized abandon, but should rather
| be:
|
| > "He laughed with a kind of booming abandon that made the
| whole restaurant turn around and look."
|
| Though, the non-generalized version is indeed better.
| grok22 wrote:
| It feels like your change is changing the scene? The author's
| sentence makes it seem like the laughter was not in the
| restaurant, while yours makes it seem like it's taking place in
| the restaurant. Maybe I am overthinking it!
| richrichie wrote:
| Original source found at:
|
| https://www.gutenberg.org/ebooks/37134
| richrichie wrote:
| Some HN folks here are so thin skinned that they down vote a
| reference to Strunk and White?
| mattbee wrote:
| It's definitely nothing new but good advice bears repeating
| over the decades :)
|
| For big picture stuff on writing I also like "On Writing
| Well" by William Zissner and "First You Write A Sentence" by
| Joe Moran (which is a bit more British).
| svat wrote:
| Was your comment ("Original source found at...") intended to
| be a reply to some other comment, rather than being a top-
| level comment? Or did you actually mean to suggest that the
| original source of the post here ("What I think about when I
| edit (2019)") is Strunk and White? The latter seems pretty
| misleading and inappropriate.
| Tomte wrote:
| > 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".
| alpinisme wrote:
| Williams' book is really excellent. It deserves to be more
| widely read.
| microflash wrote:
| Indeed. However, it is the most oft-repeated consequence of
| using Passive voice. In general, I use active voice and when it
| makes sense, passive voice is used as well.
| gghh wrote:
| Thanks for the references. I'll check them. I'm extremely
| biased against the business use of passive voice, to the point
| of getting so worked up when someone does it with me on mail or
| slack, that I need go to a quite room and relax for 5 minutes.
|
| _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.
| jodrellblank wrote:
| The opposite:
|
| "I've just created your virtual machine" - 3 year old,
| "mummy, mummy, /I/ did this! praise ME!". Got to insert
| yourself as the first thing in the sentence, as if the
| customer cares who did it.
|
| "Your virtual machine is ready" - Waiter, assistant,
| comfortable out of the limelight to let the focus be on the
| customer and what they are interested in.
|
| "I've just created your virtual machine" - You didn't make
| the deployment pipeline, you didn't build the hosting, or
| write any of the hypervisor or guest OS, you ran one script
| and now you're taking all the credit. Embarrassing.
| gghh wrote:
| Good point. Focus on the customer. Didn't see that aspect.
| lootsauce wrote:
| My brain must be warped by using LLMs because I could not help
| but think that it would be an amazing prompt, complete with
| multiple examples of each principal. Perhaps good prompting is
| good writing?
| swayvil wrote:
| I thought the same.
|
| (I did something similar in drawing. So it's a not uncommon
| path)
|
| Get your art sharp. Digest that into a science. Digest the
| science into automation.
|
| (And yes, one could argue that the result is a crystalline
| turd.)
| ano-ther wrote:
| 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 call
| out the source of an action.
|
| "The pull request got merged by the maintainer."
|
| Yes, you can misuse it to fudge responsibility, but you don't
| need the passive to do that.
| medstrom wrote:
| "They merged the pull request" sounds fine to me.
| coldtea wrote:
| As the parent notes though, "the passive also allows you to
| choose whether you want to call out the source of an action",
| while "they merged the pull request" does not.
| kd5bjo wrote:
| In context, though, the passive version can sometimes make
| for smoother reading. My general rule of thumb is that each
| sentence should establish context at the beginning by
| referring to the preceding material and then introduce its
| new idea at the end-- Whether it's best to start with the
| maintainer or the pull request depends on which of those
| you've already been discussing. (I didn't come up with this
| idea, but I unfortunately can't remember where it came from)
| svat wrote:
| Possibly from here?
|
| * _The Science of Scientific Writing_ (1990) by George
| Gopen and Judith Swan: https://web.archive.org/web/20240120
| 063715/https://www.ameri...
|
| They say:
|
| > _In our experience, the misplacement of old and new
| information turns out to be the No. 1 problem in American
| professional writing today. [...] Put in the topic
| position_ [the beginning of the sentence] _the old
| information that links backward; put in the stress
| position_ [the end of the sentence] _the new information
| you want the reader to emphasize._
|
| It's a useful article, that I also mentioned in this
| answer:
| https://academia.stackexchange.com/questions/85286/why-do-
| re... -- see also this video
| https://www.youtube.com/watch?v=jLPCdDp_LE0 of Judy Swan,
| one of the co-authors (the accompanying handout is https://
| web.archive.org/web/20170331212200/https://www.cmu.e...).
| KineticLensman wrote:
| I was once caught in a contractual dispute that occurred
| because the author used passive. The contract basically said 'X
| will be done' without identifying whether the customer or
| contractor was expected to do X. Unfortunately this wasn't
| spotted until the contract was in place.
|
| 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"
| RheingoldRiver wrote:
| This is a fantastic list of like, "suggestions to writers by
| editors" but I don't think it's a great list of "how to edit."
| The single most important thing when editing (imo) is "how can I
| preserve the author's voice?" Editing is not writing a new draft,
| it's amplifying the original.
| publius_0xf3 wrote:
| >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.
| KineticLensman wrote:
| 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
| layer8 wrote:
| This is good advice.
| mike-the-mikado wrote:
| 'This' paragraphs are fragile to editing. Ensuring that your
| text is robust to updates (e.g. insertion of an extra
| paragraph) is good practice.
| wodenokoto wrote:
| "This piece of advice", I guess it's good advice just don't
| overdo it?
| susam wrote:
| 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 where
| a team is responsible for developing and maintaining some service
| known by the name, say, ABC, but nobody in the team knows what
| ABC really expands to. In such instances, in order to avoid
| choosing a new name and updating all related documentation etc.,
| the only recourse is to treat ABC as a proper noun and move on.
|
| Fictitious example: To obtain an access token for CDIS, first go
| to DMC at <https://dsc.prod.example.com>, click on the entry for
| "CDIS" on the left sidebar, click "Generate Access Token", and
| copy the token.
|
| What I would like to read instead: To obtain an access token for
| Customer Data Indexing Service (CDIS), first go to Data
| Management Console (DMC) at <https://dsc.prod.example.com>, click
| on the entry for "CDIS" on the left sidebar, click "Generate
| Access Token", and copy the token.
| HeavyStorm wrote:
| A glossary is the most important document ANY project should
| have and maintain. Everything else is secondary.
| drittich wrote:
| Please explain what ANY expands to...
| lawn wrote:
| 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.
| mike-the-mikado wrote:
| Perhaps in terms of the importance to effort ratio. How
| long does it really take to maintain an adequate glossary?
| liamwire wrote:
| Agree strongly. I think an even more insidious version of the
| parent comment is when common nouns that have specific
| meaning in a given context are used as such, without it being
| explicitly called out.
| hcarvalhoalves wrote:
| Agree. A glossary is a way to introduce a domain piecemeal,
| without a long-form explanation.
| nuancebydefault wrote:
| I find glossaries quite often not very useful because they
| tend to get copy/pasted across documents and the acronyms are
| often just expanded without giving the correct meaning in the
| context of that document. I'd rather have it fully spelled at
| first usage, with the acronym in brackets. This enforces a
| more natural order of writing and reading the document and
| provides a better context.
| wildrhythms wrote:
| I see this happen in non-technical spaces too... product
| managers using project-specific acronyms and codenames in front
| of an audience of new people. I can't tell if it's some form of
| narcissistic gatekeeping, or just lack of mindfulness and deep
| entrenchment in the project for too long. I am so hyper
| conscious of this that I will stop meetings to ask the
| presenter to define the terms.
| andsoitis wrote:
| > What I would like to read instead: To obtain an access token
| for Customer Data Indexing Service (CDIS), first go to Data
| Management Console (DMC) at <https://dsc.prod.example.com>,
| click on the entry for "CDIS" on the left sidebar, click
| "Generate Access Token", and copy the token.
|
| Even better:
|
| _< a href="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.
| brainzap wrote:
| I think the google guide to technical writing recommends to
| write out acronyms once per chapter/section.
| _tom_ wrote:
| Should always be on first use, of course.
| tpoacher wrote:
| I'm always tempted to go passive-aggressive and misinterpret
| the acronym. I don't, but I'm tempted to.
|
| E.g. "Couldn't we simply write an email to the Computer, Data,
| and Information Services department for the access token? This
| keeps a paper trail, and explains why you need Digital Media
| Credentials in the first place."
|
| I'm someone who's jumped from Medicine to CompSci. Each field
| uses their own obscure acronyms that highly intersect. I'll
| spare you the embarrassment that comes from someone making a
| "Pro Rectum" request.
| vundercind wrote:
| HTML has an entire tag for this. There is _no_ good reason not
| to define those _every_ time they appear.
| _tom_ wrote:
| This is a related to my number one problem with technical
| writing or text books: forward references.
|
| "Let's talk all about a topic we will define three chapters
| from now"
|
| Learning about things with undefined terms, concepts and
| acronyms is much harder and may require multiple passes over
| the material.
|
| It's a hard part of writing a linear book about a topic that's
| probably a graph, but good writers manage it. Bad writers just
| leave their readers confused.
| wodenokoto wrote:
| All in all I think it is a good and well written guide.
|
| I'd like to add support for using passive voice in work /
| business emails. This is great, not only for obscuring blame, but
| obscuring the _opportunity_ for blame.
| cs02rm0 wrote:
| Is there a service for this? (Standard developer question).
|
| 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.
| gghh wrote:
| Well, a copy editor maybe?
| https://en.wikipedia.org/wiki/Copy_editing
|
| I've never used one, but I assume there are professionals for
| hire to do this.
|
| In fact I've read one of the advantage of going with a
| publisher (as opposed to self-publishing) is they give you an
| editor. But again, I'd expect a freelance market to exist.
| tomsmeding wrote:
| > completely left field to my normal technical work.
|
| I'm assuming this is another baseball reference. As a non-
| American: what does it mean? :)
| bbx wrote:
| A lot of the tips in this article are very similar to the ones
| provided in this fantastic book: The Elements of Style [1]. I
| highly recommend it, even for a non-native speaker.
|
| [1] https://www.amazon.com/Elements-Style-Fourth-William-
| Strunk/...
| gghh wrote:
| If I could add one prescription to TFA, it would be to avoid
| using _" just"_ (the adverb, as in "simply") at all costs.
|
| _" A monad is just a monoid in the category of endofunctors."_
|
| Maybe it is, maybe it isn't, but none of that is simple. There's
| that math joke about proof methods, and this would be "proof by
| intimidation".
|
| When describing a process: _" To measure the inverse reactive
| current in unilateral phase detractors, just use an ordinary
| turbo encabulator"_. Why "just"? Are there other methods? For
| what reason is this the preferred one?
|
| When giving advice: _" Why don't you just use a bash script?"_
| This implies your suggestion is simpler or more economical than
| my proposed approach, therefore better, but you aren't supporting
| its alleged superiority with arguments I can counter, only
| implying it.
| hansvm wrote:
| > monads, "just"
|
| I think that line is usually quoting a popular joke from a
| comedic tour of various programming languages, and "just" is
| appropriate.
|
| > A monad is just a monoid in the category of endofunctors.
| What's the problem?
| gghh wrote:
| I see. It was the first sentence that came to mind. The point
| I'm trying to make is, in my experience, "just" is often
| abused, as it conveniently relieves one from providing a
| sound argument.
| hansvm wrote:
| Totally agreed. Your other examples were spot-on, and the
| general sentiment also makes sense to me.
| aorth wrote:
| Yes, good suggestion. I've also stopped using "just" when
| speaking or writing in the last few years. You can almost
| always drop it and retain the same meaning without sounding
| rude or dismissive.
|
| I've noticed this in at least one other language I'm loosely
| familiar with (Bulgarian) and it holds there too. When the
| speaker adds "prosto" it has the same effect of sounding rude
| and dismissive.
| gghh wrote:
| Right: rude, dismissive, patronizing. Gives me exactly this
| impression, you put it into words better than me.
| chungmin wrote:
| What is TFA?
| zoya99 wrote:
| Hello everyone! This is my post! I'm flattered and honored that
| it resonated with many of you. Since I wrote that post, I
| followed my curiosity to become a software engineer myself. After
| doing that work for a few years, I've found myself missing
| working in a more writing-heavy role. If you're looking for an
| excellent technical writer, developer advocate, or another role
| that blends communication expertise and technical skills, let me
| know! You can contact me through the form on my website
| (https://evaparish.com/contact) or via LinkedIn.
| avg_dev wrote:
| I really got a lot out of the article. I think it will help my
| write more succinctly and clearly and to be better understood.
|
| One question: after writing the sentence "I really got a lot
| out of the article.", I wondered: is this extraneous? Is this
| clear? Am I saying precisely what I mean? And I think, yes, I
| meant exactly what I said, and I went into detail in the
| following sentence. I am just curious what you think.
| nuancebydefault wrote:
| Your first paragraph is clear, indeed the first sentence is
| the gist, the second explains it in more detail. The second
| paragraph -- the question and own answer -- seems a bit
| superfluous to me.
| korymath wrote:
| I am not the author, and am sharing feedback because you
| asked with honest curiosity.
|
| Your writing is not clear to me. Using the word "really" is
| extraneous. Using "I think" is also extraneous; I assumed
| these are your thoughts.
|
| As the author notes, replace "it" with "the article", or
| better yet a specific quote or idea distilled from the
| article.
|
| Helped "my write" should be helped "me write". You use two
| -ly adverbs, which could be avoided by restructuring the
| sentence.
|
| You also have a list of two (succinct and clear) and then a
| single item (better understood). Consider breaking these two
| thoughts into separate sentences.
| stavros wrote:
| I really (err, vehemently) disagree with this feedback.
|
| > Your writing is not clear to me. Using the word "really"
| is extraneous.
|
| What's not clear? He said the article helped him, it seems
| pretty clear to me. The "really" was for emphasis, which is
| fine.
|
| > Using "I think" is also extraneous; I assumed these are
| your thoughts.
|
| "I think" indicates the degree of certainty. The author is
| uncertain but deems it likely.
|
| > As the author notes, replace "it" with "the article", or
| better yet a specific quote or idea distilled from the
| article.
|
| The previous sentence says "the article", and the next one
| says "it" to avoid repetition. Saying "the article" twice
| would be awkward.
|
| Very odd feedback, given how obviously out of place the
| corrected sentence would look.
| swayvil wrote:
| This is smart stuff. All of it makes good sense. I speak as a
| compulsive editor.
|
| You can tighten it up, and tighten it up again, and sloppy
| doggerel becomes so clear.
|
| Really a lovely piece of writing about writing.
| alphazard wrote:
| I've heard English teachers cargo cult the passive voice thing
| for ever.
|
| This crowd will understand the passive voice as a form of
| abstraction. If anything could suffice as the subject, then it's
| not important to the meaning of the sentence, and you convey that
| in English by implying but not specifying the subject (the
| passive voice).
|
| In scientific procedures for example, the whole point is that
| anyone could replicate it. 30 grams of goop was added to the
| beaker. Doesn't matter if it was you or one of your coworkers, or
| another group trying to replicate.
| natdempk wrote:
| When I learned about passive voice, scientific writing was
| often mentioned as an explicit exception. What you say makes
| sense when you are abstractly describing something that
| happened, but also I'd argue that "We added 30 grams of goop to
| the beaker" or "Added 30 grams of goop to the beaker" is
| clearer than "30 grams of goop was added to the beaker".
| Depends on the context and style conventions of course, but
| often passive voice is still poor/indirect writing in many
| scientific contexts.
| Scubabear68 wrote:
| This post is a great set of ideas for writing. What the author is
| doing is constantly putting himself in the shoes of the readers,
| and thinking "what does the reader need here?".
|
| Which may sound like a very tortuous way to write. But it becomes
| instinctual after a while. When I'm writing and don't apply rules
| like this, I inevitably feel lost - and I know the reader will be
| too. When I end up going down a bad road like this, at some point
| I will throw away most or all of what I've written and start from
| a fresh perspective. I guess this would be my one addition to the
| author's rules: don't be afraid to throw away lines, paragraph,
| or even the whole thing if it's not working for you.
| k__ wrote:
| I needed the repetition tip the most.
|
| I always feel like repeating myself makes the text unwieldy and
| then clutter it with "this".
|
| Grammarly always complains, "What is this refering to?"
|
| Well, obviously a concept of the previous sentence!
|
| I will repeat myself more often and then rephrase the repetition.
| BossingAround wrote:
| Honestly, I would recommend never using "this" or "that" - it
| often makes sense only after you force the reader to re-read
| the sentence.
| BossingAround wrote:
| I would add eliminating future tense. There's very few times when
| future tense is actually required. It's one of my pet peeves when
| docs say something like "Click X. This will open a prompt ..."
| when it can say "Click x. This opens a prompt ..."
| euroderf wrote:
| Yes. The user is living (i.e. working) in the moment, and so
| should your text.
| Karellen wrote:
| > _Who are you writing for?_
|
| This is the hardest part of writing for me, especially blog
| posts.
|
| I can never decide if I'm writing for a) highly technical readers
| who know 95% of the concepts my idea is based on, and I just want
| to connect the concepts together in a way the they might not have
| thought of, b) generally technical readers who have a grasp of
| the concepts my idea is based on, but will need some details to
| tie them into the idea I'm building on top, or c) readers who are
| not-especially-technical in the field, who might be nevertheless
| be interested in how a few things works, and my idea too.
|
| I feel like part of it is that I am all these readers, depending
| on the subject. I enjoy reading articles about the areas of
| software dev I'm deeply interested in, but also about the odd
| idiosyncrasies of software that is used in fields I don't
| normally cover, but I also enjoy reading articles about e.g. the
| challenges involved in developing geothermal drilling systems, or
| elevator systems in 80+ story buildings, despite having very
| little experience in either.
|
| I keep going through cycles of "If I just explain this part in a
| bit more detail, the post will be accessible to an order of
| magnitude more readers" to "this is way too long, I should cut
| some explanations, or add footnotes, or more wikipedia links" to
| "I'm assuming way too much previous knowledge here, or asking the
| reader to do too much extra work to follow my point".
| VladTheImpalor wrote:
| Good question, and one I'd like to see discussed more too. From
| my point of you, your point "a)" is the one I never choose. In
| my opinion, one could rarely write something for that audience
| which might be novel to them. Perhaps I'm just not that smart,
| but to me, when I picture the true masters in my field, I
| rarely need to communicate anything to them that they haven't
| figured out for themselves already, and in the rare case that I
| might, those types of people don't mind a bit of revisiting of
| the fundamentals anyway.
|
| My favourite type of writing is one that also comes in handy to
| myself a couple of years down the line, which inevitably
| involves a modicum of handholding and starting from some
| fundamentals. So I'd say most of the articles should be b) or
| c).
| kens wrote:
| Yeah, I find picking the audience difficult too. For my blog
| posts, I want to include the details for specialized readers,
| but also make the post accessible to the generally technical
| readers (roughly the HN crowd). (If I wanted to write for only
| the first group, I'd write academic papers.)
|
| My solutions are to add enough background for someone who isn't
| an expert (even if it seems repetitive), and to use extensive
| footnotes for information that most people won't care about.
| Also, I try to put topics into a broader framework: a few
| paragraphs on history and why the topic is important. A
| narrative framework helps too, so even if someone doesn't
| follow all the details, they get a sense of going on a path
| e.g. from problem to solution. I also try to break up massive
| chunks of text with photos or diagrams but worry that I lean on
| this too heavily.
|
| When I read popular books on scientific topics, I try to study
| the techniques that they use. For example, "An immense world"
| is crammed full of interesting facts and stories, keeping the
| book even though it is discussing technical concepts of sensory
| perception. "Immune" describes the immune system in detail,
| making heavy use of metaphors and imagery and repeating these
| throughout the book. Other books focus on the people, moving
| the technical details into the background.
|
| I'm no expert on this, of course. People seem to like my blog
| posts, though, so I figured I'd share my thoughts.
| quaddo wrote:
| Back around 20 years ago I was with an MSP. We depended heavily
| on having a well written - as current as possible - prod guide
| for all operations.
|
| At some point it occurred to me that there was likely a way to
| draw upon the experiences of those who came before us. In my
| case, it seemed fitting to use newspapers as a reference.
|
| Somewhere I'd come across a concise guideline, a list of do's and
| don'ts. The only thing I clearly recall now is keeping the key
| info "above the fold", which is likely something that might
| puzzle someone who has never handled a newspaper. Even so, the
| concept is easy to share and grasp.
|
| I wish I'd kept that list. I've tried looking for it within the
| past couple years, to no avail.
| ARandomerDude wrote:
| > Don't use adverbs
|
| > There is nothing _inherently_ wrong with adverbs. They are just
| part of a category of things that I believe are lazy in writing.
|
| Comparing this quote to the rest of the article, it appears the
| italics convey vocal emphasis. I find it somewhat ironic that
| "inherently" is an adverb.
___________________________________________________________________
(page generated 2024-04-06 23:00 UTC)