131–138 of 138 posts
I did not know I have been erroneously omitting commas in English. In Slovenian, my native language, commas always delimit clauses in a sentence. We got that from German, which got it from Latin.
I still don't understand why English chose to omit commas in some cases. It just confuses the reader of larger sentences. In some fiction books the omission made some sentences completely unreadable. Granted, it was the author's fault but still... Why?
Earlier quoted context omitted.
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.
That part, I do not get. Do they mean it permits a rewrite? But all sentences do.
If the PR introduced a BUG or was a bad choice to merge it, you might not want to use an active form, because then you have to say who did it (for example, in a report), to protect them, or to not appear like you're pointing fingers. The passive voice allows you to state the fact that the commit was merged, without mentioning anybody.
"John/Jil merged the pull request"
vs
"The pull request was merged" - you can chose whether you want to include "by John/Jil" or not.
Earlier quoted context omitted.
> 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…
> Even small teams of 4-10 people can benefit from shared common terminology The team size has very little impact on it's value, it's entirely dependent on the turnover of the developers. I guess I wasn't clear enough as it seems you didn't understand what I meant to express at all. With every sentence you wrote I just had another question mark appear over my head
1) You answered to the parent that whether "term may not map cleanly to a single OOP class" doesn't matter, because "it will map to either entities or functions".
My answer was that it might not map to those either, but still be useful to talk about the software, and good to be shared by the developers and other shareholders like UX and sales.
2) That "An argument against documenting it on the entities and functions would be that this would spread the information across the repository", and having a single markdown file gives better overview.
I agreed, and even expounded on that: "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."
3) That "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"
And I retorted that even smaller teams - meaning teams that don't are anything like the above, including not having high turnover, can benefit from this. Even without any turnover, people forget. So when getting back to further develop or debug or refactor, etc, some piece software it's good to have documentation of key types, concepts, and terminology, from when you originally wrote it.
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 techni…
And editor should know they should use 'whom'.
> Example: If you’re looking for me I’ll be in my office. > Revision: If you’re looking for me, I’ll be in my office. > Example: Due to the fog our flight was delayed. > Revision: Due to the fog, our flight was delayed.
If the sentence is unambiguous without the comma then lean towards omitting it. Especially with the second example, with the clause being only four syllables long, the comma slows down the reader so much that the music of the sentence is broken. "Fog our flight" cannot be misinterpreted — nobody thinks of fogging a flight. Indeed the lack of a comma foretells to the reader they can confidently plow ahead through a well-tended sentence.
Also on the topic, Larry McEnerney's 2014 video "The Craft of Writing Effectively" https://www.youtube.com/watch?v=vtIzMaLkCaM (100m). He was Director of the University of Chicago's Writing Program.
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.
> completely left field to my normal technical work. I'm assuming this is another baseball reference. As a non-American: what does it mean? :)
According to the 2007 Concise New Partridge Dictionary of Slang and Unconventional English, the phrase came from baseball terminology, referring to a play in which the ball is thrown from the area covered by the left fielder to either home plate or first base, surprising the runner. Variations include "out in left field" and simply "left field"
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 techni…
You using HTTP in the example without explaining it, was really funny. Was that joke on purpose?
When you write anything, you have to assume your audience is at some baseline of understanding the topic. Otherwise, every software article would have to begin by explaining what a computer is.
In an article about optimizing web performance, it seems like a reasonable assumption that the reader would would already understand what "HTTP" means even if they don't recognize the abbreviation "TTFB."