Something that I always keep in mind is the rather complete and thoughtful GitLab Documentation Style Guide [1].
1. https://docs.gitlab.com/ee/development/documentation/stylegu...
Just Simply – Stop saying how simple things are in our docs
121–130 of 299 posts
Re: Just Simply – Stop saying how simple things are in our docs
#122I think those words do convey useful information. If, for example, a student is told that a theorem has a simple proof, she will find it faster than if she does not possess that information, because the search space becomes smaller.
Re: Just Simply – Stop saying how simple things are in our docs
#123As a math professor, I had an epiphany about the word "easily" several years ago. In my course notes, I used that word to mean "I guarantee you don't need any additional ideas here, just do the obvious thing." Nothing more was meant.
But I realized that many students either didn't think the obvious thing was really that obvious, or maybe realized it but were reticent to follow that path because it invoved some tedious work and the prof said it was easy, so that couldn't be it.
Many students were also intimidated by that word, as if I were saying to them "if you don't find this easy, you shouldn't be here".
So I went on a deleting spree, removing most instances of "easy", "simple", and "just a matter of", and replacing them with a clearer explanation of what to do. My notes got better as a result. Less filler, less intimidation, more useful details.
Re: Just Simply – Stop saying how simple things are in our docs
#124My stance is really not in favor or against using (or overusing) a word from a "blacklisted" set, it's more that usually the structure doesn't cater well to the audience and on top of that it adds a lot of unnecessary fluff. If I need to download X dependencies but two of them need to be version 1.2.3, by all means tell me it's all super simple to do, idc, really. But give me the exact dependencies that NEED that ver…
It bothers me when someone good/bad naturedly corrects me on "blacklist" and encourages me to say "blocklist". I figure that stems from either overactive empathy or is a power play. Please continue to say "blacklist".
I see “blocklist” becoming more popular in programming. But it just occurred to me how bizarre and out of place it would be if the parent comment said “a blocklisted word”.
Re: Just Simply – Stop saying how simple things are in our docs
#125Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…
When you hire new people and they encounter this over and over again, onboarding drags on so, so much longer than it should, because people taking your position never think "we should reduce how complex this is", they think "they should stop being babies", and things just get progressively more obtuse and annoying and require more and more tribal knowledge instead of making sense.
It's not the word "simply", it's that if you think every thing that's easy for you is therefore easy, you're communicating that you don't think that understanding other people's experience matters.
Re: Just Simply – Stop saying how simple things are in our docs
#126Earlier quoted context omitted.
> The post is about Please reread the comment you are replying to. He’s talking about the hacker news comments.
The very first sentence of their comment is an appeal to the article. They're addressing the article and using HN comments as evidence to reinforce their perception of it. "Stop saying how simple things are in our docs" "Or maybe -- controversial opinion here -- people shouldn't be such babies"
Yes, it’s possible to alter the meaning of something by quoting a sentence out of context.
If you continue reading to the next sentence, it becomes explicitly clear that he is addressing the comments here.
Re: Just Simply – Stop saying how simple things are in our docs
#127I agree that words like simply and just should not be used in documentations, but are people really getting upset about it? I couldn't imagine being this fragile
Think a little harder, then. It was written for a reason. They even bought a domain and hosted this one page, for a reason. You think they did all that because they were fragile?
...maybe? Why would fragility be a less likely explanation? I promise, I'm thinking as hard as I can but maybe I'm too dumb.
Re: Just Simply – Stop saying how simple things are in our docs
#128Personally I prefer that type of sentences, it allows me to know which procedures are easy once you know them, and which aren't. If you are new, everything is difficult. But if you read that something is simple you know that, even though for you right now it isn't, it will be in the future. If you have issues with that simple task, maybe you are doing it wrong and should ask for help. On the other hand, if the docume…
and should ask for help
By... reading the documentation, for example?
Re: Just Simply – Stop saying how simple things are in our docs
#129Or maybe -- controversial opinion here -- people shouldn't be such babies. I'm looking around the HN discussion here and can't quite believe how personally offended people are by these words. Yes, at the beginning of the first semester at university, hearing a math professor say a step is "trivial", when it was quite hard, was a bit grating. One month in, I realised that the intended meaning of the word was that no s…
> Is that the reason why tech documentation has slowly been evolving into 50-minute step-by-step YouTube tutorials that start with installing the IDE? What happened to the expectation of people being adults?
I think this really proves that writing good documentation is a skill you can hone.
In my opinion, if you're writing a package, gem, etc. for a web framework:
Having extremely concise documentation where you assume the person using your tool is already an expert, so you skip everything except for the precise details related to your tool can be frustrating for anyone looking to use your package unless they happen to be at a skill level where they could have written the package themselves. If folks can't figure out how to use your tool, they'll use something else.
Having extremely verbose documentation to the point where you rewind things back to installing an IDE or explaining what a for loop is for an extension related to pagination is equally as frustrating for most folks because they already have the basics down and want to figure out how to use your package.
I'm a firm believer that good documentation for such a tool or package would include the "why" with a few practical examples along with a guide-like approach of explaining how to get it to work where you use title headings and bullets to make it skimmable as a reference at the same time. You can still make it concise while covering all of that ground. I see nothing wrong with having both text and video.
This way you satisfy a wide range of skill levels without frustrating or alienating anyone. This approach isn't coming at it from an angle to "protect" anyone either. It's optimizing for general success where success is defined as anyone other than yourself can use the package with minimal'ish friction.
Re: Just Simply – Stop saying how simple things are in our docs
#130As a math professor, I had an epiphany about the word "easily" several years ago. In my course notes, I used that word to mean "I guarantee you don't need any additional ideas here, just do the obvious thing." Nothing more was meant. But I realized that many students either didn't think the obvious thing was really that obvious, or maybe realized it but were reticent to follow that path because it invoved some tediou…
Thank you! I think you correctly guessed what the students were thinking, because I have thought similar things.
One angle here is that academics are (rightly) proud of their specialist knowledge, and often using words like "simply" and "easily" really are a flex whether they know it or not. The best way as student can take this is as inspiration, that one day it will be easy for you, too. I personally believe empathy deserves high praise and recognition, a key part of pedagogy. However, the lack of empathy does not, in turn, deserve derision. Not everyone is a great, or even particularly good, teacher.