23 ms·
Just Simply – Stop saying how simple things are in our docs
- userbinator 3y ago...unless it's actually simple. Unfortunately a lot of software these days (especially the "modern" stuff) does not qualify.
- alpaca128 3y agoYes, often it's used for things where you "simply" have to install a dependency which does so much stuff its official website can't tell you what it is, then you have to figure out how to install precisely version 3.9.7 because another one won't work for this, and of course use that one workaround to initialize it the first time, and you're set unless one of the 10 git clones in some script fails. Many things could instead be as simple as "python main.py".
- unsupp0rted 3y agoIt’s very difficult to tell what is actually simple
- junon 3y agoOne of the best pieces of advice I learned in high school from an incredible English teacher: when doing technical, avoid "-ly" words entirely. It has always been solid advice and has rarely led me astray.
- stavros 3y agoWhat, like "butterfly"?
- sametmax 3y agoLike "otherwordly", obviously. Never use "otherwordly" ph'nglui technical documentation, ngnah ymg' risk s̵͖͕͓̒̾̾ǘ̵̢̺͓͊́m̵̟͙̓̒̚m̴͉̠͖̈́͊͠o̸̞̺̻̾́̀n̵͖̻͓̓̔i̴̢͚͕̿̕͝n̴͇̞͎͒̀̚g̵̢̟͙̾̚͝ z̴̪̠̟̾̿͘a̸͇̞͙̔͌͛l̵̢̟̘͆̒g̴͓͔̀́̿ö̵̪̠́͑̓.̴̢͙̪́͝͠
- rzzzt 3y agoAvoiding "butterfly" when writing technical documentation sounds like a good advice.
- loloquwowndueo 3y agoThe keyboard in your thinkpad 701C has a mechanism we affectionately call butter… oh never mind.
- rzzzt 3y ago"Affectionately"?! One point for Slytherin!
- latexr 3y agohttps://en.wikipedia.org/wiki/Butterfly_keyboard https://en.wikipedia.org/wiki/Butterfly_keyboard
- BellsOnSunday 3y agoC-h f butterfly
- Hendrikto 3y ago> avoid "-ly" words I hope this isn’t the actual advice you were given. They are called adverbs.
- junon 3y agoIt was the exact advice given. Not all adverbs end in "-ly", either, and not all adverbs should be avoided in technical writing; that'd be impossible. The rule states "-ly" words because those words are often cruft or crutch words that can be removed. If the sentence can't stand on its own without that word, then the sentence probably doesn't belong in the body of technical writing. Compare this with time-related adverbs, which generally provide chronological structure. Those are more relevant for technical writing. So yes, avoid "-ly" words. Not adverbs in general. That was the advice given.
- nohuck13 3y agoSome adverbs not ending in "-ly" are always, soon, today, ever, yet. "The Python interpreter has a number of functions and types built into it that are always available." [1] "Long option values can be split across multiple lines simply by indenting the continuation lines." [2] Agree with your teacher in that the first one seems fine. [1] https://docs.python.org/3/library/functions.html https://docs.python.org/3/library/functions.html [2] https://docs.python.org/3/distutils/configfile.html https://docs.python.org/3/distutils/configfile.html
- sorokod 3y agoI think that the advice is a bit more nuanced, your first example is fine as it is but consider the variants: "...that are clearly always available." "...that are obviously available." "...that are simply available." These adverbs are not only redundant but their presence suggest that things are actually not clear, simple or obvious.
- Fnoord 3y agoFor non-native English speakers -ly is simpler than adverts. But simpler does not necessarily mean better long-term.
- commandersaki 3y agoThis is a rule in the Hemingway app: https://hemingwayapp.com/ https://hemingwayapp.com/
- latexr 3y ago> when doing technical, avoid "-ly" words entirely. Following its own advice, “entirely” can be cut without loss of meaning. Considering the replies you’re getting, perhaps a better way to phrase it in the future would be: > eschew "-ly" adverbs. That way it’s clear you’re referring to a specific subset of adverbs.
- deleted 3y ago[deleted]
- sametmax 3y agoIt's a more and more popular opinion: - Why not tell people to "simply" use pyenv, poetry or anaconda (https://bitecode.substack.com/p/why-not-tell-people-to-simply-use https://bitecode.substack.com/p/why-not-tell-people-to-simpl...) - Don’t use the word ‘simply’ (https://jameshfisher.com/2017/02/22/dont-use-simply/ https://jameshfisher.com/2017/02/22/dont-use-simply/) - Stop using ‘simply’ in tech instructions (https://www.parkersoftware.com/blog/stop-using-simply-in-tech-instructions/ https://www.parkersoftware.com/blog/stop-using-simply-in-tec...) - Don’t say “simply” in your documentation (https://www.knowledgeowl.com/blog/posts/dont-say-simply-jim-fisher/ https://www.knowledgeowl.com/blog/posts/dont-say-simply-jim-...) And I strongly agree. It can be so discouraging to fail at something you should "simply" do. But to be fair to the technical writers, it's easy to write that way without noticing, even after proof reading. This should be automatized by writing tools. Also, while it's mildly irritating, there are worse things in life. Yet as the first link about the python ecosystems notes, it usually hides a bigger problem: many devs are too good to be helpful.
- kqr 3y agoI remember reading one of those and it made a huge impression on me. I've followed it ever since and taught others to do the same. As far as I can tell, it has only been met with appreciation. That said, sometimes I find myself trying to write around "simple" when I really mean "less complex", and I have to remind myself that what I really want to avoid is implying "easy", not "relatively less complex".
- sametmax 3y agoIndeed. I tend to force myself to write the following: - It will be easy => I will guide you through it - This will make your life easy => It will make your life easier / It will help you - To do X, simply do Y => The most common way to get to X is first to do Y
- sjrd 3y agoYou can use comparatives, like "simpler", usually without issues. Something can be simpler than something else without necessarily being simple. Superlatives like "simplest" can sometimes be used as well. After all, being the simplest thing means to be simpler than all the other things; still not necessarily simple. It's only the positive form "simple" which is problematic and should be almost always avoided.
- blueflow 3y agoRegarding docs: Most recent projects that i looked into and tried evaluating are very focused on the shiny parts and all the nice features it got and bells and whistles.... it sometimes reads like an ad or an sales pitch. But, I'm a sysadmin. I will be carrying operational responsibility for that thing if we decide to adopt it. I'd love to know what are the most common modes for it to break, what the cuts are where you could swap in your code, resource usage, update cycles and stability guarantees of these updates. Existence of a downgrade path (looking at you, kubernetes!). Ideally you'd know ahead if you are getting something robust where you can safely take a week off without any risks or something that needs to keep a firefighting team on-call for the rest of its lifetime. I think a lot more needs to be done on the docs than omitting some words...
- flockonus 3y agoNot to jump on GPT hype too much, but a good idea perhaps for an addon targeting OSS, read over issues, PRs, scrub Stack Overflow and compile a descriptive list of the most common pitfalls for a certain lib. It's exactly the type of writing OSS authors don't like doing, and all the information is publicly available.
- sametmax 3y agoThe problem is a lot of it is not publicly available. E.G: I asked chat gpt to help me install Python on Ubuntu 22.04, and it failed miserably. Why? Because 22.04 is recent and many pitfalls it comes with haven't been much documented yet. And it also don't know what is never written, but implicitly known if you deal with a lot of beginners. E.G: people get utterly confused with *args and **kwargs in Python, because it can be used at 2 different places, and depending of those places, it does completely different things. The latter is well documented, but that the brain of people cannot grok it is not. So chatgpt will explain the same things as most of the doc, without realizing that what it needs to do is to warn humans that they are going to be confused and how to avoid it. Humanity has a lot of implicit knowledge.*
- incone123 3y ago
- sixhobbits 3y agoWe simply delete the word simple and just remove the word just when we see it too. Some similar simple writing rules that we've found just improve writing overall here [0] https://styleguide.ritza.co/ritza%27s-writing-rules/Style/ https://styleguide.ritza.co/ritza%27s-writing-rules/Style/
- BiteCode_dev 3y agoThe word does have some value though. I'd rather replace it by something that means "it's a popular way to do it", "it will help you to do it that way", or "it's recommended for beginners to use this procedure".
- nelsondev 3y ago+1 to the article. I’ve noticed this more recently. Ironically, it seems to be more common with coding communities known for their welcoming spirit and helpful nature, for example Rust. Gratuitous repetition of how easy something is can make it feel harder when understanding is not immediate.
- toyg 3y agoI think it's more common in technical communities trying desperately to persuade people that their obscure low-level tech is not as obscure and low-level as it actually is -- for example Rust (but also Linux, C/C++, BSDs, networking, etc). The post is right: if you're explaining something, it's because the other person could not understand it without help, which means it's not, in fact, easy. It might be easy to repeatedly use it once you understand it, but it's not easy to grasp in the first place - otherwise you wouldn't have to be there in the first place.
- charcircuit 3y agoIf simple things like running a command isn't simple for you then the docs were written for a different target audience than you. Just because I'm checking the docs it doesn't mean that something isn't simple. It is just impossible for me to know or remember everything about everything even if some of those things are simple. If you aren't the target audience that doesn't mean you can't use it, you just might end up needing to ask for help from someone who is from the target audience.
- tremon 3y agoIndeed. Or, put differently, proclaiming things to be "easy" in your documentation mainly serves to scream "go away!" to new users.
- vdm 3y agoplease add "blazing fast" to this list
- euroderf 3y agoand anything and everything "unleashed"
- BiteCode_dev 3y agoPreferably with zero benchmark or one with a clearly artificial setup.
- unsupp0rted 3y agoRock star ninja rocket emoji Rick and Morty gif
- Hendrikto 3y agoThis is really annoying to read on my relatively small phone screen. There is way too much whitespace and only about 4 words per line.
- marginalia_nu 3y agoSimply get a computer.
- EGreg 3y agoIt’s like when I was growing up, I always found it hilarious that the seller on TV touted a “low low price of ONLY xyz”, and they marveled at their own offer! As a kid, I realized that this is silly… it us the buyer who determines if the price is affordable or not. Most advertising in the last few decades just spouts nonsense in an effort to get you to buy something.
- unsupp0rted 3y agoThey use it because it works on people with IQs that are average or below, even adults
- WesolyKubeczek 3y agoYou’d be amazed how many people still watch this shit in 2023 and even buy it, when 1) you can quite easily* find what cheap product is this a rebrand of *admittedly not so easily since Google became extremely enshittified in the last fiveish years 2) drop that product into any old ebay or a price comparison engine and marvel at the markups they rack 3) find reviews of the same and see how those products come apart when you look at them funny, or are made of plastics known to cause cancer wide outside California, or some shit But then again, it’s my bubble, outside of it it’s far from “obvious”
- tpmoney 3y agoNot that the commercials were this deep, but the ability to afford something by the buyer doesn't change the relative pricing compared to the market. If I throw a 3 bedroom house on the market in a HCOL area for $200k when every similar home is going for $500k, it's a perfectly truthful statement to say it's being sold for a "low low price of only $200k". The fact that is out of the price range of a part time fast food worker is irrelevant. Though it's probably worth using "low low price of only" as a marker to investigate why something is so much cheaper than it's market price.
- commandersaki 3y agoDid this article really deserve its own domain?
- has_many_books 3y agoone down [checks account on dnsimple.com] 59 to go...
- ykonstant 3y agoIndubitably.
- lpil 3y agoPeople can get domains for whatever they want, you don't need to earn them.
- toyg 3y agoThis is absolutely true. It irritates me to no end when I read something that goes "oh, flooricating is so easy, you just scombobulate the foolarizer with bardotic parameters like this: <magic incantation>". No, dude, it's not easy: if it were, we wouldn't be here - most people don't like to read manuals or even ask for help, if they can avoid it.
- throwaway14356 3y ago[This library] makes it even harder to [do difficult thing] I will suffer you through it, at the end you will hate me, be more confused and have even less of an idea how to use [this library] [Complicated thing] made more complicated and harder. I will have you do many difficult things and remember them just to do [difficult thing]. Good luck, you are going to need it!
- wouldbecouldbe 3y agoWording is one thing, but what is always annoying moving to a new library or language is the tacit knowledge the docs assume. It's a fine line, one can assumes a certain knowledge to even be functional, but in doubt I think it's better to be extra verbose. Few examples: - JS libraries not showing how to import the modules used in code examples. - Everything in the kubernetes docs - In Xcode explanations often it just mentioned: go the "build settings", etc. In beginning it's extremely confusing to find anything in that program.
- imiric 3y agoI agree with the article, but to be fair, all software aims to simplify a task. So calling a procedure "simple" is usually done in comparison with what used to be more difficult/complicated. Though my biggest annoyance with this is when it's part of network protocol names: SNMP, SMTP, TFTP, etc. What you usually find when working with these is that they're far from being simple, so it borders on false advertising. Maybe they start that way, and that is the author's vision, but when they mature it often stops being true. Or maybe they were simple compared to what predated them, and for their time and place. But it's still a bad idea to name a protocol or standard that.
- BossingAround 3y ago> I agree with the article, but to be fair, all software aims to simplify a task. So calling a procedure "simple" is usually done in comparison with what used to be more difficult/complicated. It follows that calling anything "simple" is redundant. Either it's implied (i.e. "of course it should be simple, otherwise I'd just use X"), or it's wrong. Indicating the difficulty of anything has no place in any technical text.
- kazinator 3y agoSo, it's off limits in a technical text to say that, say !(!a && !b) simplifies to a || b, or anything else in a similar vein?
- rikschennink 3y agoSuper frustrating. There’s a lot of “just do x” in stack overflow answers as well. It “just” makes the reader feel stupid.
- jabradoodle 3y agoBig agree, everytime I find myself typing a comment on slack along the lines of "can we just do x", I immediately stop and delete the word just. The message doesn't loose any meaning and is a lot less obnoxious.
- TrianguloY 3y agoPersonally 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 documentation says that something is hard, you shouldn't even attempt it as a beginner, and perhaps wait until you have more experience.
- kqr 3y ago> If you have issues with that simple task, maybe you are doing it wrong and should ask for help. Far more common, in my experience, is that the author considered it so simple they did not spend any effort explaining it adequately. I.e. they were so distanced from their target audience (by virtue of their amassed experience) that they forget to adapt the text for them. There are other, more descriptive ways to explain that things are more or less complex for experienced users.
- tremon 3y agoand should ask for help By... reading the documentation, for example?
- has_many_books 3y agoalso available in pandemic-remote-conference-talk format: https://brightonruby.com/2020/just-simply-emma-barnes/ https://brightonruby.com/2020/just-simply-emma-barnes/
- paradox242 3y agoI get this a lot while reading about something new which I have heard might solve my problem, or while better trying to understand a system already in place. The documentation begins with a comforting high level description that is vague enough to sound like it might fit my use case, but then abruptly transitions into a table of contents listing the minutiae of interfaces, API calls, system components, without giving a suitable intermediary description of how any of these things might work in concert to actually solve the problem. This is left as an exercise to the reader. You will almost never be offered any central insight from the author(s) about their mental framework for the system they have designed, or even that of the problem that it is intended to solve (so that you might more quickly determine whether your particular problem is a member of this class). Instead, I will often find this missing information presented in a random blog of some individual who, having won this knowledge through heroic effort, is determined to provide the context that they would have wished to find themselves upon first starting their journey. Why does it have to be this difficult? I suspect a lot of this has to do with the organization of companies involved (Google and Microsoft are some of the worst offenders here) in that the people writing the documentation are often not the people creating the systems, and so don't really understanding anything they are describing themselves. Meanwhile, those that designed the system suffer from the Curse of Expertise where their familiarity blinds them to things that are "obvious" to them, but are not actually inherent to the system they have designed. They are ignorant of all of the background understanding and experience that lead them to design the system or approach the problem in a particular way, when this is actually the most valuable thing I look for in any documentation I read.
- WesolyKubeczek 3y agoI’ve seen worse. — an emoji-laden intro employing borderline UwU-speak — jumping into API reference immediately after — the reference is auto-generated with half of it being stubs, implying you should throw it away and just simply read the code
- kstenerud 3y agoReminds me of the turbo encabulator presentation [1]. Quote: "The latter consisted simply of six hydrocoptic marzlevanes, so fitted to the ambifacient lunar waneshaft that side fumbling was effectively prevented." [1] https://www.youtube.com/watch?v=Ac7G7xOG2Ag https://www.youtube.com/watch?v=Ac7G7xOG2Ag
- lelanthran 3y agoHaskell believers should read this. Look at this recent response to "that's not simple, by definition alone": https://news.ycombinator.com/context?id=35756937 https://news.ycombinator.com/context?id=35756937
- kstenerud 3y agoNow that I've written a few specifications (which tend to have a much higher explanatory burden), I've come to appreciate just how difficult it is to write introductory material to a subject that you're an expert in. Like any skill, it takes a lot of practice.
- ModernMech 3y agoLol, yeah the first time I attempted it, someone got so frustrated they posted an expletive laden issue on the repo. There’s some real latitude to go wrong here!
- rusl1 3y agoI like that the example is talking exactly about Rails Mailer. I've used it once and it was really painful to setup, which is exactly the post point. Love it.
- _RedPanda 3y agoI 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
- lucidguppy 3y agoLearning tech through documentation is hard for some people. People who try to make something easy by force of "magic words" is pretty common in the tech industry. People who write the docs likely do not want the reader to feel stupid. This is low hanging fruit and good advice. No one is screaming or fragile here.
- throwawaaarrgh 3y agoThink 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?
- infinitezest 3y ago...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.
- codeflo 3y agoOr 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 special clever trick was required to make the deduction, just a lot of perseverance. Similarly, when documentation mentions to "simply" do something, and I don't get it, isn't that a clear hint that I'm still missing a concept somewhere and need to look around for an explanation? What I wonder is: Why is this so personal? Are people really shamed into quitting their career over a misplaced "simply" in a piece of tech writing because it triggers their impostor syndrome? 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?
- jstummbillig 3y agoResilience and good communication don't share an axis. You can want and have both. To me, the examples in the article make a convincing case for what's stronger writing and that's good enough.
- vrnvu 3y agoI agree with your point. Nowadays, people seem to be overly sensitive about their code and the way we communicate, among other things. It's important to remember that the code is not a reflection of ourselves, and not everyone will be pleased with it. Some will provide good guidance, while others will not. Therefore, we should remove our ego from the code. Code is like a lollipop that we enjoy, but then discard once we're done with it. If I don't understand a design doc, it doesn't necessarily mean that I'm stupid or that the writer is bad at communicating. It may simply require more effort on my part to fully comprehend it. I don't understand why some people are so sensitive and take everything as a personal attack.
- rco8786 3y ago> Nowadays, people seem to be overly sensitive about their code and the way we communicate, among other things. If there's one thing I've learned in life, anytime you see "Nowadays" or "these days" or something similar, you can be guaranteed that whatever statement follows it is a universal truism about the human condition that recency has no bearing on. People are sensitive about their work. And sensitive to how we communicate together. Always have been. Always will be.
- robertlagrant 3y agoThis is just yet another politeness law, adding some more words we shouldn't use. There is a useful message though: make writing clear and unadorned.
- delta_p_delta_x 3y ago> There is a useful message though: make writing clear and unadorned I think this is the key takeaway. From the example in the article, phrases like 'just', 'painfully simple', 'just another way' aren't instructive nor objective, but decorative and subjective. Documentation should have exactly one purpose: to instruct. There ought to be no mentions of difficulty, or obviousness, or triviality, or any other smart-aleck commentary. It ought to have a direct, clear tone, such as 'do X, which causes Y. Now do A and B, which requires C.' and so on.
- jtwaleson 3y agoI see it differently. If you are writing documentation for a system you know a lot about, things are completely simple for you right then right there. But as we all know in 6 months you'll look at your own code and think "who the ... wrote this?". So avoiding the word "simple" isn't about accommodating the 5% of your least intelligent users and dumbing down the content, but the > 90% who are not so into the topic as you are right now.
- robertlagrant 3y agoClarity, yes. But not specific rules. Or we're back to the Plain English Campaign simplistic "only write in the active voice" silliness.
- schwartzworld 3y ago> If someone’s having to read your docs, it’s not “simple” The opening quote of the article is so stupid. If the docs are enough to teach you to use a tool, that seems quite simple to me.
- magwa101 3y ago[dead]
- vinaypai 3y agoI don't entirely disagree with the sentiment, but the example is so contrived. The problem with these sentences isn't that the word "just" and "simply" are somehow upsetting to the reader but that they're clumsy sentences. "Mailers are really just another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they are just sending it out through the email protocols instead. Due to this, it makes sense to just have your controller tell the Mailer to send an email when a user is successfully created. Setting this up is painfully simple." That said, I think there's rarely a good reason to say something is "simple" in documentation. Explain how to do it and let the user decide if it's simple.
- has_many_books 3y agoIt wasn't an example: it was copied and pasted from the Rails guides at the time.
- vinaypai 3y agoOh wow, okay. That sounded so bad I didn't think it could possibly be from the real documentation for a pretty popular product.
- has_many_books 3y agoI know: bonkers!
- meotimdihia 3y ago15 years of experience in web development. And I'm a tech leader but still have a hard time to understand Amazon S3 docs.
- tarkin2 3y agoIt's annoying and sometimes demeaning and often tactical when managers use it. In docs it can be annoying when there's assumed knowledge and skills. And it adds nothing except to indicate how another may find the activity--why bother adding it? Simply improve your docs, people.
- chrismorgan 3y agoGood discussion in 2021 (249 points, 138 comments): https://news.ycombinator.com/item?id=27418577 https://news.ycombinator.com/item?id=27418577
- brunooliv 3y agoMy 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 version for the thing to work. Worse than this unnecessary fluff and eagerness for simplicity or wtv is having incomplete instructions that lead to a non-working setup by the end. Proofread them by EXECUTING them and then, as long as it works, be a Shakespeare about it. There seems to be a lot the expectations of things being broken and a kind of tragedy of the commons being the standard.
- EdSharkey 3y agoIt 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".
- bvinc 3y agoI 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”.
- School-Cotton 3y agoPlenty of people now say allowlist and denylist instead of whitelist and blacklist.
- WesolyKubeczek 3y agoGoodlist and ungoodlist.
- WesolyKubeczek 3y agoBlocklist for me is a list of blocks, like the one you gather with badblocks(8) and then pass to fsck(8).
- dale_glass 3y agoWhile we're here, could we also please have clear separation between commands and data? Eg, I hate stuff like: $ bin/rails generate scaffold user name email login Which is it? $ bin/rails --generate=scaffold --user=name --email=login Or: $ bin/rails --generate=scaffold --user=username --name=fullname --email=address --login=login_name Or: $ bin/rails --generate --scaffold=user --name=fullname --email=address --login=login_name Or what?
- bombcar 3y agoEspecially when we have the entirety of modern monitors available to us, use color to indicate which parts of the command/code are mandatory/boilerplate and which are optional, and which are the actual "values" you'll be using.
- teddyh 3y agoColor might not be available, like here in HN comments. In older texts, the <angle-brackets> convention was common, but became less so probably due the emergence of HTML. Nowadays, I most commonly see the $SHELL_VARIABLE convention. Man pages use UPPERCASE_ITALICS (or uppercase underlined on terminals).
- seri4l 3y agoI'd say it's the last one, with a "subcommand based position dependant syntax" like git or zfs. It's a matter of taste but personally I prefer it to the traditional one. As long as the behavior is consistent remembering the order of the arguments is often easier than remembering the exact keywords.
- ekimekim 3y agoThe long-standing convention here, particularly for command line usage, is that: - String literals should be in lowercase (because by convention commands, argument names, etc should always be in all-lowercase, eg. "git cherry-pick" not "git cherryPick" or "git CHERRY-PICK") - Metavariables (stuff the user should fill in) should be in ALL-CAPS. - Not as strictly adhered to but still useful, [optional part] and {repeatable part}. So eg. your example might look like: $ bin/rails generate scaffold --user=NAME --email=LOGIN and an example usage would then be: $ bin/rails generate scaffold --user=ekimekim --email=ekimekim@example.com As far as I'm concerned, for documenting command usage, there is no excuse not to use this scheme.
- nmca 3y agoGive up 70% of the way into the hyperstitious slur cascade. https://astralcodexten.substack.com/p/give-up-seventy-percent-of-the-way https://astralcodexten.substack.com/p/give-up-seventy-percen...
- lucidguppy 3y agoI agree with the post. If you consider that your docs are also a form of advertising... don't shoot yourself in the foot and make your readers feel stupid. I would go one step further. If we are talking about CLI tool usage - the cli should have two modes. One interactive using gum or some similar library. Once complete - it should output the non-interactive equivalent CLI command. The interactive run should give short explanations to help learn the tool. The takeaway point is that docs are partially advertisements - and if you don't want to lose people - your docs have to be carefully crafted.
- _throwawayaway 3y agoOfftopic but i wish devs would offer light theme too.
- beepbooptheory 3y agoSomething 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/styleguide/ https://docs.gitlab.com/ee/development/documentation/stylegu...
- mdaniel 3y ago> Write in US English with US grammar. (Tested in British.yml.) heh, that was funny but it turns out the file is a list of British words checked using Vale, which I just learned existed: https://github.com/errata-ai/vale#readme https://github.com/errata-ai/vale#readme (MIT) Also, another TIL is that the "e" version of gray is British https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml#L58 https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale... I had previously erroneously assumed they were just one of those quirks of English (which, I guess is still true but it is less random than I thought)
- EVa5I7bHFq9mnYK 3y agoI 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.
- apricot 3y agoAs 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.
- javajosh 3y agoThank 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.
- ellisv 3y agoWhenever my professor said "it's easy to show" and then moved on it felt very hand wavy. The steps weren't obvious to me and didn't become more obvious as the course went on because no one taught me how to think of the "obvious" thing.
- javajosh 3y agoThe worst situation in my college experience was when a prof would go over some mundane part of a proof in excruciating detail, and then hand-wave the important part. I realized later in life it was because they prof didn't understand it, either.
- Waterluvian 3y agoI have embraced the idea that nobody wants to read what I write. I think that everyone is going to close my document at any moment, so I communicate as clearly as possible. My tech writing reads like it’s for kids, but coworkers seem to like it.
- layer8 3y agoThis describes a trivial way to improve your documentation, by simply just eliminating words like “easy” and “straightforward”. (I agree with TFA.)
- mhb 3y agoYes. It's a subset of removing noise words. Like excising "like" from speech. Or not starting sentences with "So...". "Obvious" should also be on his specific list.
- Myrmornis 3y agoAgreed. I've submitted PRs removing the word "simple" from docstrings. If you find yourself writing "This is a simple wrapper around...", what you meant to write is "This is a wrapper around...".
- qznc 3y agoI wish people would stop conflating "simple" and "easy". Git's core internals are simple but using it is not easy. Simple things can have very complex implications. If an API is too simple, you have to build complex things on top to make it work for you. Python is easy for beginners but it isn't a simple language. In fact, it belongs to the more complicated ones. Making something easy usually requires a lot work.
- frou_dh 3y agoCheck this out: https://github.com/search?q=%22simple+yet+powerful%22 https://github.com/search?q=%22simple+yet+powerful%22 Biggest clichéd phrase out there in marketing to developers.
- vrglvrglvrgl 3y ago[dead]
- karmakaze 3y agoThe problem isn't the word "simple" it's words like "just". Within something complex, there can be a simple thread of reasoning that may not be easy to see and once communicated, everything takes shape and begins to make sense. That's worth communicating even if it's not easy to describe. Often that may be how the author came about the design. I wouldn't know how better to describe such a thing. Explaining all the complicated things that make the simple thing work ends up with the reader being able to agree with all the explanations, then wonder "yeah, but why do those all add up to do what it does?" Tone of writing is important, but also a reader shouldn't assume that something that has a simple core is easy to make or later understand. I'd say it's more constructive to have your docs show how/why it's simple rather than make a statement and leave it up to the reader to piece it together. What's a better word than "simple" that doesn't make it also imply "easy" to many? e.g. the elevator thought experiments of General Relativity are simple, but not easy to come up with or initially reconcile.
- perrygeo 3y agoThe problem with using "simple" is that it's ambiguous. Are you talking about the opposite of sophisticated? the opposite of difficult? the opposite of complex? It has virtually no meaning without context. So if you're tempted to write simple, remove it and say exactly what you mean. Often times, documentation writers say "simply do X" when they mean "as a prerequisite, this document assumes the reader has an understanding of Y such that they can accomplish X without any further instructions". There's nothing wrong with having prerequisites; you have to assume the reader has some knowledge upon which to build. Make that explicit rather than hidden behind a "simply".
- antognini 3y agoWhen I was in high school I did Moot Court. I remember our coach telling is to stop using the word "clearly" in our arguments. His point was that if it really was so clear you wouldn't be in court arguing about it.
- phkahler 3y agoHow about we stop telling people how simple, fast, efficient or whatever our software is. Let users decide for themselves. Tell them what it does and how to use it.
- jmartrican 3y agocough cough Spring cough cough
- eric-burel 3y agoMy fav game with a new tool is to take "simple" features and break them on equally simple use cases that are not documented. The most popular libraries are with no surprise the ones that resist this game the best. To give example, I like React and Next.js new beta documentation because they do not stick to being a reference but also explain the rationale and show real-life usage as much as possible.
- btown 3y ago“With fewer lines of code” is not the same thing as “simpler” - particularly, if it’s an abstraction that requires the user to understand the underlying mechanics, the more verbose code may be significantly more self-evident. If you’re writing even an internal API and this thought pops into your mind, put yourself in the shoes of a junior colleague and ask yourself - or ask one directly! - if a little bit of boilerplate is actually a good thing. And, to the OP’s point, if you do decide to make these abstractions, using terms like “brevity” rather than “simplicity” can be a big part of gaining adoption.
- tristor 3y agoGiven the state of software documentation in general, I am okay with any word choices the author wants to use, even the downright offensive, as long as it means they actually document the software thoroughly. I have way bigger fish to fry than the emotional response I have (or don't have) to a given word.
- Smaug123 3y agoI'm surprised nobody has pointed out yet that "Mailers are another way to render a view" has lost information that was present in "Mailers are really just another way to render a view.". The author of this post appears to want to adopt the most infuriating traits of the MSDN documentation: namely, converting all documentation into a list of facts ("Mailers are another way to render a view", "a common use of mailers is…"). This is bad because if you are presented with a bare list of facts, you can't judge their relative importance, or how they relate to each other. The original Rails example was bad, but rather than fix it, they have rewritten it to make the badness more obvious. The original was bad not because it uses the words "just" and "simply", but because it's verbose while still being hard to read. I still don't understand what the sentence starting "Due to this" is trying to say, and it's very unclear where they transition from giving general technical facts to walking through the specifics of the example. (It is certainly wrong to call something "painfully simple" - I can imagine maybe one or two places where it's ever appropriate - but it's not the main thing that is wrong with those docs.) But the first two sentences of the original docs were easier to understand than the rewritten version. Compare: > Mailers are really just another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they are just sending it out through the email protocols instead. > Mailers are another way to render a view. Instead of rendering a view and sending it over the HTTP protocol, they send it out through email protocols instead. I mean, is it rendering a view or isn't it?! The second version explicitly contradicts itself much more baldly than the first version, where the words "just" performed an important function by indicating that the sentence is about what is different between mailers and other renderers. In the rewritten version, two of the three sentences of the first paragraph explicitly contradict each other, and the third is totally unrelated to what came before. This was a structural deficiency of the original docs, but removing the narrative elements of the text has amplified the problem to the point of absurdity.
- Uvix 3y agoBoth versions are bad, because in both cases the first sentence says that mailers are "another way to render a view", while the second sentence says they are another way to "send" an already-rendered view. > I mean, is it rendering a view or isn't it?! It is rendering a view, and both versions make that clear. There's no contradiction in the rewritten version.
- ho_schi 3y agoGermans here? Klicken sie einfach auf “Ausführen”. Click simply on “Execute”. The writers of manuals love the word “simply”. There is just one problem: If you need instructions it is NOT simple for your users. The word doesn’t add info. The text to comprehend becomes longer. And the task even harder for readers. I started using “einfach” too much and now delete it whenever appropriate.
- lnxg33k1 3y agoI mean sometimes things are simple, and are put in docs because someone doesn't get what's obvious, I had to sometimes to shut myself from offending people who were stuck on screens that were so obvious and instead of trying and fail or google, waited for the help of someone to unstuck them, docs exist with simple things inside and that is not enough to measure if those things are simple or not, they also exist like if that one guy who couldn't understand the obvious and had to ask, does a doc that documents something that was understood without it by 999 people, make what is documented unclear because of 1 that couldn't see? if you go to a place where you see a sign "Don't touch the fire", does it make not touching the fire not obvious because the sign exist? Or we have to put obvious sign for those who aren't cerebrally developed enough to understand it without the sign?
- bityard 3y agoDid they really buy a whole domain to host one short op-ed?
- has_many_books 3y agoI've got to do something with them...
- intalentive 3y agoI think people say “just simply” because they’re proud of having reduced a boatload of complexity to a couple steps. It says implicitly, “If only you knew how much work I’ve saved you!” Maybe there’s also an aspect of “customer service”, where the writer adopts the tone of a smiling amusement park tour guide. I can see a cheerful female intern writing docs like this. A no-nonsense Richard Stallman type, not so much.
- deleted 3y ago[deleted]
- mistercow 3y agoI disagree with this pretty vehemently. There is value in a doc telling you “this sounds like a complicated concept, but it’s actually not”. As a reader, it can tell you that you don’t need to dig for deeper meaning or start searching for and understanding all the related concepts. This particularly comes up when a concept has an unfamiliar name because of how it fits in with things conceptually, but at its core it’s just a very familiar entity with some other familiar entity tacked on, or something like that. For an example off the top of my head: “A tagged image is simply a JSON object with an ‘image’ data URI property, and a ‘metadata’ object property”. The word “simply” is pulling weight here. It’s telling the reader that there is nothing else to the concept, that they already understand everything there is to know, and they can move on. This can be misused, of course, and I think the post’s example is a valid one. But it’s a lot more useful to say when you should use something in your writing than it is to say “you probably shouldn’t.”
- ulizzle 3y agoYou shouldn't use "simply" because it's an adverb and an overused one, but this mumbo-jumbo about feelings is giving me the creeps. The example given reads better because it cuts out the adverbs. I'm assuming Grammarly or something similar helped to lint it. Such cringe.
- aliasxneo 3y agoIf you configure your Grammarly in formal mode (i.e. documentation), it will automatically suggest removing almost all of these words. The purpose is to reduce verbosity.
- desro 3y agoI don't share the author's POV describing this sort of thing as "infuriating" or anything else that dramatic, but the before-and-after documentation example was definitely more readable and clear (I've never worked with rails [ruby?]). So I support the overall premise here. It's nice to read documentation that is at least verbose enough to give you additional keywords to search with if you need more help, and I do feel a little bit more respected as a user when it feels like someone took time and care to write the docs with juniors in mind. I think that a lot of the tutorials available on Digital Ocean are actually good examples of this; though they're not "docs" per se.
- firexcy 3y ago> a lot of the tutorials available on Digital Ocean are actually good examples of this Second this (although the qualities of DO’s tutorials can vary greatly). Indeed, their “Technical Writing Guidelines” [1] agree with the author: > We avoid words like "simple,” "straightforward,” “easy,” “simply,” “obviously,” and “just,” as these words make assumptions about the reader’s knowledge. While authors use these words to encourage and motivate readers to push through challenging topics, they often have the opposite effect; a reader who hears that something is “easy” may be frustrated when they encounter an issue. Instead, we encourage our readers by providing the explanations they need to be successful. [1] https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines#comprehensive-and-written-for-all-experience-levels https://www.digitalocean.com/community/tutorials/digitalocea...
- taeric 3y agoSimplicity is asserted as much as it is true. Such that, you will be surprised how effective saying something is simple is at getting uptick in it. My goto evidence for this, for a while, has been Python. It is no "simpler" than pretty much any other option nowadays. What it has going for it is an audience that as bought in to how simple it is. And they evangelize it. With those terms. Heavily. Is it somewhat obnoxious? I mean, yeah. I'm very sympathetic to the idea. At old job, we would harp on "weasel words" that were there and served no purpose. But, there is a catch, they absolutely work on audiences that are not primed against them. Can they be overdone? Absolutely, but there are solid reasons you will see them over and over.
- chazeon 3y agoThese are excellent before-after example pair I can ask GPT to analyze then apply the technique to my own writings. I hope there are more examples like this.
- calsy 3y agoNot sure I've seen the sentence 'Setting this up is painfully simple.' used often in any documented instructions. It's unnecessary and rather arrogant.
- why-el 3y agoThis is a new rephrasing of an older mantra, which is to use fewer words when possible. The writings of the greats in our field exude this quality, for instance those of Dennis Ritchie. Mind you, he does use the aformentioned words, but they are often necessary, for instance, using the wording "simple shell" is true, because the shells he developed were indeed simpler than the ones before, and provably so. The only twist in this new take is that it has an issue with commanding language using such words, and I agree. If you are telling me how to do something, there is no need to qualify the effort, because you don't have that information and neither do I, so the language ends up being verbose and, more crucially, incorrect.
- gumby 3y agoI understand the author’s point yet think it’s OK. Why? Because when I encounter “simple” in that context I read “If you understand the domain this package allows you to perform calculations (or whatever) and will operate in a way you will expect”. Some examples: IEEE floating point is a simple FP standard, even though the document is really long and full of non-obvious cases and a couple of footguns for the naive. It’s simple for someone doing serious numerics (and even simple for a most common cases with a little training) because someone put the hard work in, so the user doesn’t have to code up allot of infrastructure. MS word makes it easy for someone like me to change font sizes, center some text etc, but a sophisticated designer probably fights Word’s DWIM and would prefer a more sophisticated tool with more knobs, because that would be simpler for hem to use. And so on.
- patrickmay 3y agoThis reminds me of my time at Amazon where it was hammered into us to avoid weasel words: https://www.factoftheday1.com/p/amazon-writing-style-tip-3-184c76dd2bb7 https://www.factoftheday1.com/p/amazon-writing-style-tip-3-1... Eliminate anything like "just" and vagaries like "simple."
- tomcam 3y agoWhile we’re at it, let’s stop saying “add additional“. “Add” means the same thing
- savanaly 3y ago"Add milk to that cereal" vs "Add additional milk to that cereal" If that was all I heard of a conversation from the other room, I would form two different ideas of what was going on in that room, hence they can't mean the same thing.
- tomcam 3y agoI cheerfully confess that you are right. I also assert that this would be a tiny minority of uses where this would make sense.
- blacksoil 3y ago> If someone’s been driven to Google something you’ve written, they’re stuck. This is not true. When I evaluate new technology to decide whether to use it or not, I tend to Google or HN around to see what people think about it. The words "just" or "simply" can be a good expression somebody uses to express their opinion about the library.
- thejazzman 3y agoI personally only use heavy-weight, slow, complicated and hobby grade JavaScript.
- chauhankiran 3y agoEven further nowadays, docs are created using Docusaurus. I don't have problem with it but documentation should be good (eye) friendly than easy to write. Why not be creative while writing docs such as - Backbone.js - https://backbonejs.org https://backbonejs.org Or https://backbonejs.org/docs/backbone.html https://backbonejs.org/docs/backbone.html as code annotation. jQuery - https://api.jquery.com/ https://api.jquery.com/ Bootstrap v3.x - https://getbootstrap.com/docs/3.4/ https://getbootstrap.com/docs/3.4/ Go docs - https://pkg.go.dev/std https://pkg.go.dev/std
- 6451937099 3y ago[dead]
- 6451937099 3y ago[dead]