13 ms·
If someone’s having to read your docs, it’s not “simple”
- astrange 5y agoAnother thing you should not do is name things “fast”. It will end up not being fast (esp when you find the next faster thing) or else someone will find security holes in it.
- itsmemattchung 5y agoAgreed. Same thing with "Smart".
- 3np 5y agoIn my mind, "smart" now means something along the lines of "proprietary non-interoperable blackbox surveillance appliance sending your data to arbitrary cloud endpoints for profiling". I am yet to fit a clever backronym for it.
- stevenpetryk 5y agoSubtly Monitoring At RunTime
- duskwuff 5y agoDitto "better", "simple", and "[yet] another".
- inputvolch 5y agoYou're right. In fact everyone should stop trying to paint any of their products in a positive light.
- mseepgood 5y agoAlso, it's always relative.
- segfaultbuserr 5y agoSo far, Fast Fourier Transform and Quicksort still holds up well (there are faster algorithms, but both remain adequate choices for general use). But I do agree with you, they're exceptions rather than the rule, e.g. Fast Ethernet, only 100 Mbps ;-)
- astrange 5y agoFFT does, but the FFT library fftw ("fastest fourier transform in the west") is no longer the fastest from what I understand. FFmpeg originally stood for "fast forward" but no longer means anything. They do have this problem where they need to replace older APIs with newer ones - their approach is to give the newer ones names with "2" "3" stuck on the end instead of "fast" "faster" etc. But there are some problems in there, there's something called "simple IDCT" which I have to admit I never fully understood.
- justin_oaks 5y agoAnother one is avoid referring to something as "new". Soon enough it will be old. For example, class names "MailSender" and then you add "NewMailSender". What do you call it when the "NewMailSender" is old?
- TeMPOraL 5y agoThe same thing you do with your Word documents. NewNewMailSender. NewNewMailSenderFinal. NewNewMailSenderFinal2. NewNewMailSenderReallyFinal. And so on.
- dariusj18 5y agoLatestNewCountdown2Final.docx
- doublerabbit 5y agoFinalLatestNewCountdown2v3.docx
- itsmemattchung 5y agoAnother word I often see riddled in our code base is "Obviously". It might be obvious to the original author ... but not the reader.
- warent 5y agoYears ago, I read Michael Crichton's autobiography "Travels". In that book there is one particular part that, for whatever reason, cemented itself in my memory. He recounts how his father shared a lesson with him regarding the word "Obviously", and it was something along the lines of "If you say it's obvious, but it isn't, then you will offend someone. If it is obvious, then it's superfluous. The word 'obvious' never needs to be used" I've applied this ever since then and almost never use the word anymore. There are some rare times I find it's useful though, for example if you want to reassure someone that they come across the way they intend to, or in some positive manner: "Obviously you care a lot"
- itsmemattchung 5y agoThat's a good point. I've also tried to eliminate the word "obviously" from my vocabulary. The one exception, as you pointed out, is reassuring someone in some positive manner.
- wccrawford 5y agoI use it whenever I feel the need to say or explain something, but I'm 90% sure the listener already knows it. Failing to say could lead to a failure at a critical time, but explaining it like they're a simpleton could lead to them being upset about that. So I soften it with 'obviously'. But this almost always needs to be someone I have report with. Without knowing the listener, I can't really judge what they'd know or not. And on the web, it's probably not time-sensitive at all, and it's a lot easier to skim the explanation.
- andi999 5y agoWell it conveys the information: no further documentation on this available anywhere
- jmadler 5y agoBrought to you by "just simply dot dev"
- bobbytakeitwith 5y agoI believe that is the point?
- jmadler 5y agoYeah, sorry, I wasn't being sarcastically ironic or anything.
- ilrwbwrkhv 5y agoThis blog is again hard to read.
- anm89 5y agoI've had a blog post rolling around in the back of my head for years regarding how "obviously" is the absolute worst word to use in any kind of technical context. And then go through some of the most egregious things labeled as obvious in various peer reviewed research or blog posts.
- gumby 5y agoMe: new (to me) high school, 1978. In the headmaster’s western civ class. In the first test (three questions, answer one, use as many blue books as you need) I wrote, “Obviously...”. When the results were handed back I looked at my book. Where I had written, “obviously” he had crossed out that word and a lot of subsequent text. He wrote, “since it was obvious I didn’t bother to read it.” Forty odd years later I have never forgotten the lesson which affected me not simply in regards to the word “obviously”. (The whole class failed that test and there followed quite a bit of instruction on how to to do schoolwork. I now wonder if it even counted against our grade?)
- Dylan16807 5y agoSometimes an obvious thing needs to be brought up as context for a future statement. His reasoning there is blatantly wrong. And omitting the word "obvious" wouldn't make the statement any less obvious. Wouldn't his explanation demand he cross out any basic true statements, no matter how you worded them? There are good arguments for avoiding the word "obviously" in many circumstances... but I don't buy that argument.
- Animats 5y ago"Obvious" in mathematics is seldom defined. It does, though, have a specific meaning. Something is obvious if applying standard solving techniques without planning ahead will work. That is, backtracking will not be necessary. In this sense, symbolic differentiation is obvious, but symbolic integration is not.
- swalladge 5y agoI've had a draft for a similar post lying around for a long time too - this would be about the word "just". It's used too often to undervalue work (just a hobby project, just a webapp...) or be misleading about the complexity of things (just set the dns entry, just solve the halting problem).
- cbracketdash 5y agoWow I could not agree with more with you. I think I'm finally improving my writing skills as well ! Also, I find it hilarious that you have an entire website dedicated to make your point. I would give a +2 for that ;)
- has_many_books 5y agoOP here: many thanks for my +2!
- JoeyBananas 5y agoDo not use adverbs in technical writing period
- BrissyCoder 5y agoYeah - I don't actually think I've ever seen that kind of language in technical docs. I don't think this problem exists. Maybe for some very experienced juniors... but you'd hope they'd get that silliness slapped out of them by more experienced colleagues rather quickly
- NateEag 5y agoI have seen this plenty of times. I can't quantify it, but I saw the title and thought, "GOSH yes. I HATE those kinds of docs."
- yourapostasy 5y ago> ...I don't actually think I've ever seen that kind of language in technical docs. I agree I don't see that in Big Vendor Co. product documentation where Procurement cut a 5+ USD figure check to license it per year (or equivalent subscription). In internal documentation within a company, I see that kind of language all the time. Yet it is the internal documentation that so many of my clients' staff rely upon in their daily operational activities, so while the page count of the internal documentation doesn't match the vendor documentation, the use of that language there hurts my clients a lot more. This leads to a lot of the tribal knowledge-oriented activities I see in most of my clients. The documentation is so disjointed because no one in leadership comprehends how much productivity is lost (because the tribal knowledge papers over the functional loss with unperceived efficiency loss by forcing tightly coupled organizational inter-relationships, reducing organizational agility and capacity to handle complexity) when the documentation provides no pointers between the interstices of detail and scope, or hopelessly mix up the context. It is more of a mixed bag in smaller vendors' software and open source though in aggregate better than internal documentation, and the more successful Big Cloud vendors tend to be relatively better at this. But still far from Apple Macintosh programmer documentation after they opened it up more, IBM mainframe, some sets of inter-related US military field manuals. The most pernicious trend I've seen lately is a level of technical writing that can only be charitably called "symbol manipulation by non-domain familiar writers" who plug and play edits of successive versions of documentation that have been outsourced/offshored to writers incentivized by number of documentation incidents closed than actual coherency across not just the paragraph, but across the page, sections, chapters and books. English as a second language isn't their challenge; within the scope of their limited edits, it is perfectly acceptable; misaligned incentives (often arising from mis-scoped requirements) is the problem.
- MattGaiser 5y ago50% of the questions on Stack Overflow are probably because the documentation was not great in the first place. I am surprised how much configuration/installation time I spend on there.
- handrous 5y agoSomething that bugs the hell out of me is any file-location or file-name configuration-by-convention thing where every example doesn't clearly state WTF file it's supposed to go in and link to a full example to provide any necessary context. "Gee, I guess I'll scan the whole page... nope, not anywhere on this page, now I get to click around your docs menu trying to figure out where this goes. Thanks." Half the time I end up poking around on GitHub trying to find a project that uses it, so I can figure out where it goes.
- hardwaresofton 5y agoIf Stack Overflow ever changes their model/tries too hard to monetize, the resulting chaos will be bad initially, but will probably spur a shift to better documentation across the board. SO serves as unofficial documentation for a lot of projects and once that crutch is gone, it will force projects to either improve or (more likely) stop letting people file issues (because that's where all the stuff would go). Looks like GitHub is already getting ahead of this with the "Discussions" feature.
- arduinomancer 5y agoThis seems really pedantic. Are people really that sensitive that docs calling something simple feels like an insult to their competence? When the library author says “makes X simple” they mean relative to existing ways of doing X. They don’t literally mean simple in absolute terms. The statement is useful because it immediately conveys the goal of the library.
- gostsamo 5y agoIt is bad writing style as well. Streamlining the narrative in your tutorial and avoiding unnecessary words decreases the mental load of the reader.
- tommica 5y agoPersonally, I don't find it insulting, but it does sometimes in a bad day help kick-starting the classic imposter syndrome of "I don't get it, oh no, I'm a fraud..."
- hardwaresofton 5y agoRight, except if the project didn't actually make the actual thing you want to get done Y (for which you were using X) simpler, but made it harder, because the docs for the new tool are nonexistent/obvious setup for the language/platform/framework produces an error, etc. No one is complaining about projects that say they're simple if they actually are simple and easy to use (i.e. download a binary, run the binary, it doesn't break and does the ~right thing). I think this is more a reaction to when people say "oh it's simple just <huge amount of setup> and you're done!", or even worse when they say "oh it's simple just download and run" and when you do that you're hit with an incomprehensible error/notation talking about deep internals you have to configure.
- MattGaiser 5y agoThe problem for me is that it over-estimates my competence. I often have no idea how to do simple thing X as required, so would appreciate a tutorial link or a more full explanation.
- 5y ago
- lxe 5y agoAgreed, but that's quite an axe to grind, with a domain and all...
- has_many_books 5y ago:low bow:
- mikewarot 5y agoOr worse yet, docs that aren't written by a human, but extracted out of comment-less source code. There is a tendency to actually document the first point of contact with code, but nothing after that.
- chousuke 5y agoThis results in absolutely delightful documentation with things like embedded DSLs (I have suffered slight trauma from Ruby ones) where the documentation contains 90% incomprehensible voodoo incantations that exist just to make the DSL look pretty.
- csande17 5y agoIs it just me, or does this change in particular totally destroy the meaning of the sentence? Original: > Mailers are really just another way to render a view. "Edited": > Mailers are another way to render a view. The original sentence suggests that, while mailers may look different, they use the same underlying "render a view" mechanism (as some other part of Rails, presumably). The revised version makes it sound like if I wanted to render a view, I could choose to use either a mailer or some other system to accomplish that task. Like, "hmm, I really want to render this view, should I use a templating system or a mailer?"
- segfaultbuserr 5y agoI agree. The original sentence probably makes sense in context for a reader who read the docs from the beginning. I didn't read it, but I assume the author already introduced similar ways to "render a view", so saying "really just another way" implies the new one isn't fundamentally different and not all that important. On the other hand, it can sound annoying for a reader who landed to this page from a search engine. I think it shows the somewhat inevitable tension between documentation as a standlone work and documentation as a random-access reference. Nevertheless, as the author said, I do find removing the superfluous "just" after the first sentence is warranted. The original text used 3 "just". One "just" in the first sentence is enough. And definitely don't write "painfully simple". --- On second thought, if this is what you want to express by using a "just", a better idea is to say it explicitly, let me try... > Mailers is yet another option to render a view. similar to the HTTP module. Instead of rendering a view and sending it over the HTTP protocol, they send it out through email protocols instead. This can be the better alternative of both versions. Be straightforward, don't use subtle language in a technical document.
- bluejellybean 5y agoI agree with the "read from the beginning" vs "landed on a page" issue. Linking can solve a lot of these styles of issues, as does keeping in mind the many possible consumers of the given documentation. As a simple example.. Original: > Mailers are really just another way to render a view. "Edited": > Mailers are another way to render a view. My Edit: > Mailers are another way to render a view, much like the linkTo(RenderMethod()).
- tomkwong 5y agoI agree for the most part. However, IMHO using these words (just, simply, etc) occasionally can make the doc more lively and fun to read.
- justin_oaks 5y agoDo you have an example of such writing? Or produce an example? I'm having a hard time understanding how such language would make documentation more "lively and fun to read".
- deleted 5y ago[deleted]
- ehnto 5y agoI have a pretty obvious codesmell test that I apply to software codebases, Can I achieve what I need just by reading the code? If not, it probably means there is a bunch of arbitrary knowledge in configuration, transpiling, generation, linking, novel concepts or language "magic" that you will need to consult the docs for. If a codebase is idiomatic to the language its written in you really should be able to figure most things out from reading the code. At the very least my IDE should know how to autocomplete functions in the codebase without generating helper files. The helper file is essentially a list of all the missing information in the codebase that someone has had to figure out how to generate and connect.
- SV_BubbleTime 5y agoPossibly similar results if the article just said “Use the Hemingway Editor” [0] … which I have found useful in my writing. Avoid adverbs. Compromise before you get to “Why waste time say lot word when few word do trick”. [0] https://hemingwayapp.com/ https://hemingwayapp.com/
- deleted 5y ago[deleted]
- anonytrary 5y agoIs this accurate? This library] makes it painless to [do difficult thing]. [Complicated thing] made simple and easy. All you have to do is just [difficult thing]. Third line should read "All you have to do is [many, often comprehensible steps] using our API to do [difficult thing]." which, in my experience, is enough to get me in a spot where I can do enough and/or read the source code to figure out how certain edge cases are handled.
- fouc 5y ago> That’s better: cleaner, less cluttered and less, frankly, infuriating. They should add "frankly" to the list.
- pistoriusp 5y agoAs a programmer I've realized that one of my special skills are that I read the docs. It's such an understated skill.
- enraged_camel 5y agoThis is why I laugh when people denigrate modern software development as “just glueing libraries together.” Lol, as if that’s an easy or trivial thing…
- vmception 5y agoI interview people based on their ability to cheat on the assessment, as finding the answer and adapting it efficiently more closely matches the day to day job. The person that figures out how to copy and paste code for a REST call in that particular framework will still probably fail if they don't notice that they need to adapt it for the network request caching system and the ORM. But there is no reason to memorize all that syntax and regurgitate it in the most computationally efficient Big O
- pistoriusp 5y agoI think we may be thinking about this differently. I value reading the documentation of libraries that I'm using. I don't memorize it, but casually read over it to understand what's possible. I do not do this for everything, but if it's a piece of technology that I value, then it's probably a good idea to read the docs so that I'm not faced with "I did not know that it could do that" situation. The amount of times I've seen developers painfully code around something that was already supported in the library they're using is suprizing.
- vmception 5y agoI've had a handful of developers do this, mostly in frontend work with lifecycles because they didn't read
- globular-toast 5y agoThat's always been my special skill, and it's not even just programming. Back in school I was considered a "leet hacker" who was good at computers. I "cracked" an encrypted Word document when someone forgot the password to it (I Googled how to do it). I built my own PC (I Googled how to do it). I downloaded MP3s before they were everywhere (I Googled how to do it). You get the idea... Nowadays I get paid to do that stuff, but at home I fix my own car when I can, fix my plumbing when I can, fix and maintain my bicycles, do my own networking etc. How? You guessed it... I DuckDuckGo how to do it.
- deeteecee 5y agoid recommend focusing on documentation that goes through much more complex layers than fussing over this. And he's also misreading what simple means.
- has_many_books 5y ago*she
- mkl 5y agoIf someone's having to read your docs, it's not discoverable. It may well be simple to do once you know.
- manjana 5y ago> Scan your technical writing for words such as easy, painless, straightforward, trivial, simple and just. Chances are your writing will be clearer as a result of removing them. I don't know, I really love when I see someone using painless, easy or trivial, my experience is usually that. I think they are nonnegotiable if you have a clue about what you are dealing with.
- deleted 5y ago[deleted]
- jokoon 5y agoIf a library/framework doesn't provide samples/examples, then it's probably not a good library. "RTFM" isn't a valid answer anymore, unless you're being paid for very meticulous software development, with high end precision software, which rarely happens. And in this case, you generally just read the code, not the documentation. It's not a coincidence that code is written in a language, it's because it's meant to be self explanatory. Documentation is relevant for engineering products, electronics, mechanics, etc, but I think I believe that software doesn't need documentation; only the code is required. Documentation should be written as code samples, and that's it. I really think that software has been inflated and put on a pedestal as something only smart people can work with. It's not. Everyone who works in STEM, or the 25% of the most educated people, should be able to write some python.
- has_many_books 5y ago> I really think that software has been inflated and put on a pedestal as something only smart people can work with. It's not. Totally agree: that's the other website from us that didn't make it to Hacker News today https://dayofcode.co.uk https://dayofcode.co.uk
- zhdc1 5y agoI don't know if it's enough to simply provide example scripts and leave users to their own devices - even well documented code takes a while to understand. The best documentation I've seen is usually relatively easy to grok, includes example code for real-life use cases, and come with simple explanations.
- shantnutiwari 5y ago>> If a library/framework doesn't provide samples/examples, then it's probably not a good library Great point, and I'll add: The examples must cover the 80/20 rule -- 80% of the time, people just need simple examples just to get started. And the simple thing is important-- the examples must be standalone. I can't remember the number of times I just wanted to try out a new library, but couldnt even get the "hello world" version working, and just quit. It's harder if the library/code is in a language you dont use for your day to day job.
- GrinningFool 5y agoPersonal preference - I'd much rather see conversational style docs where someone is guiding me through a thing, than passive-voice docs that do the same thing only in a more stilted fashion. Though I agree, the "just"s and "simply"s are things to avoid.
- scoot 5y agoThe author of the linked article seems to be confusing documentation with a tutorial. Their examples are firmly in the latter camp. To your point - I would argue that passive voice is more appropriate for documentation, and active for tutorials.
- alephnan 5y agoI've found it less complex to just read GCP's SDKs and API libraries source code than to read the documentation.
- bnajdecki 5y agoThat's also the approach that we took in the GenDocu project - instead of writing the whole essay, you just generate code sample and the short descriptive comment. Less writing for developers, less reading for consumers.
- djur 5y agoI agree with the removal of "simply" in most cases, as well as useless flourishes like "painfully simple", but I think the example includes a case that isn't meant to be a rhetorical assertion of simplicity: > really just another way to render a view This is using "just" in the sense of asserting similarity, not simplicity. And in the context of the sentence, it's being set up as the basis for an argument: "(because) X is just Y, therefore we should..." The original document is kind of repetitive and "bloggy", with a lot of reiteration of the same ideas in a way that feels like it's meant to fill in space between code examples. But I don't think this technique of just removing particular words makes it any clearer or better.
- Kronen 5y agoThis post is stupid and it's not the first time I've read something like this. Of course it's easier now, layers and layers have been added over the years to make programming easier, simpler and for a wider audience. Almost any library is made to make a programmer's life easier and simpler, if you didn't have that library and had to fight directly with the underlying layer it would be an order of magnitude harder for you to do it. So of course it's easier, because being easier or simpler doesn't mean anything if you don't take into account what you're comparing it to. In this case with the difficulty of what was there before this particular library was written. The problem is that 30, 40, 50 years ago most of the programmers were smart people, engineers, the best of the best... Making programming simpler every year and for a wider audience has made people with no patience to want to be programmers, they want it all chewed up and they want it all now, instead of struggling with the code or documentation (if any) themselves, and they want to be programmers in a month. If this is not the case then it's because "it's really hard", sorry but no, something that takes you less than a couple of years to learn to reach an intermediate level is not hard.
- Kronen 5y agoPeople getting offended just because someone said something is easy and simple. Problems of the 21's century...
- barry27 5y ago"Being stuck is, to one degree or another, upsetting and annoying" boo hoo