Is 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?"
I 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.
I think in the Rails mailer context you're expecting "render a view" to be a comfort zone for the reader, the line is suggesting a mental model you hopefully already have that will really help you understand how the upcoming process will work. "It's kind of like view rendering, so I should expect a template file and the need to correctly set header fields."
I learn best by analogy, so the first version in the article was very helpful and comforting. The second version makes me, and I think the parent and grandparent, expect that view rendering is more like requisite knowledge than a possibly useful analogy. "Only true experts in how views are rendered need apply, I better study that first."
I 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()).
It's just you. Assuming there is a "render a view" mechanism, neither of those statements is clear about whether mailers are a way to use it or an alternative to it. And it's not clear from this text whether there even is a single "render a view" mechanism to begin with!
It needs clear wording, perhaps like "this is a wrapper around" or "this is an alternative to" or "this is one of the" followed by more detail.
I actually see just as in a lot of cases as being as a painful indication of a gross trivialization of something.
I regularly call out engineers when they say "just", in a lot of cases when I say - can you explain "just" they go and pull out their collection of familiarity and understanding. To which I usually ask - "How much of your understanding will the reader have?".
When I ask them to remove the just, suddenly a single word becomes a couple of sentences that expand the "just". Magically something trivialized becomes described.
Encountering a “just” triggers my fight or flight response. I often interpret is as something that author has done so many times they have internalised it, regardless of the complexity of the task. It also probably isn’t documented with something more than a deprecated code snippet.
I think good documentation would give a bit more orientation on the first sentence. E.g. why not mention what other ways to render a View exist and maybe even link to them
"Mailer is one of muliple ways to render a view. It translates a view into a text- or HTML-Email.
Other available Renderers are PDFWriter, Printer and CSVWriter"
Looking at this documentation in context, the point it's attempting to make here is that since mailers are rendering a view, the appropriate place to call them is from the controller (as opposed to the model, I suppose). The documentation has already repeatedly made the point that mailers are like controllers, that they render views, etc.:
> Mailers are very similar to Rails controllers. They also have methods called "actions" and use views to structure the content. Where a controller generates content like HTML to send back to the client, a Mailer creates a message to be delivered via email.
So I would argue that both the OP's suggested change and a lot of the ones in this thread aren't quite right. The reader has already been told that mailers render views. The "corrected" version misses this and tosses out the main point while preserving the repetitive throat-clearing. Within the context of a step-by-step guide, meant to be read in order, a better clarification might be something like this:
> Since Mailers are another way to render a view, it makes sense to call them from the controller. In our example, we will call the UserMailer at the time a user is successfully created.
(Whether this is actually good advice is a separate question.)
No, the first sentence does not imply that mailers use the same underlying "render a view" mechanism. I would argue it implies the exact opposite, in the mailers are just another way to render the view. The two sentences mean the same thing.
I see this 'style' many times in some docs. A bit of doc that basically describes the name of the function/class. But does not show why and how to use it, how it fits in the API system, and so on.
public void DoesXYZ()
Then many times a description of 'a public method that does XYZ' does not return anything.
It is exceedingly unhelpful but meets the 'it is documented' checkmark.
My next step would be to search for an example usage of that thing (usually landing on something like SO or some random training site). Then what sorts of items might it need to work. Why would I use it over something else? Some OK examples of what is going on goes a long way and what sets the expectation of the original dev on how they were expecting you to use it. So I end up spending some decent amount of time reading the tea leaves and if I am lucky the code itself to decode what is going on.
One feed back I consistently give to all vendors is 'your docs need examples and those examples need to be consistent with each other' If I have to open github and spend a few hours reverse engineering that code, and then also try to learn whatever language you thought was fun to play with 6 years ago, I am not going to be happy.
Exactly. Examples always trumps some convoluted explanation.
Good docs are like: "this library make you do things like this, this or this, as easy as [show code snippet 1, 2, 3]".
Also a big list of examples should be way easier to just dump into the docs than writing some absurdist essay about the tech, ie. it's even easier for the maintainers.
I vaguely remember the PHP website doing this with their functions on their website with user comments with examples - another example is Mozillas MDN.
Honestly now thinking about it, "user added examples" should be its own category on sites like Github. Seriously why isn't this a thing?
Dozens of "Here's how i used this library to do this" would be amazing.
Very much so. But many times just a small example putting the thing in context of usage helps a lot. Sometimes that is needed sometimes it is not. This style is especially useful if you have a call/anticall style like malloc and free. An example of malloc could also have an example of free along with it indicating to the reader (hey you want this too). Some docs it is not obvious what the matching call is.
That'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.
This is precisely what I have realised is my special skill as well!
I can read the manual / docs and I can cast an eye over third party packages to see how it works it astounds me that so few people take these simple steps.
Same. I'm often surprised as to how far programmers will go to disparage the quality of docs, as opposed to just reading them. Like I get that there are factors affecting their accessibility, e.g. internationalization, but it is your literal job to read this information.
Meanwhile, for reverse engineers, it's a dream come true to be granted any information whatsoever on the product they're reverse engineering. For some reason, programmers want to operate in the context?
I 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
I 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.
I _do not read_ the docs. I read the readme in githib, if there is not enough information in it for my use case, I may continue searching.
Also, when I find a lib, I want to read some user stories, not 20 pages of documentation in yet another doc format. Simple user stories. If you need to do A, here are 3 lines. If you need to do B - here are 5 lines. If your lib lacks these user stories, I will probably skip it. Or if I really need it, I will use StackOverflow to find some use cases so I can relate to and get a better understanding of the lib.
_NOW_ I may read the docs after I have the user stories, so they better have some information how you can customize the 3 and 5 lines of code above.
50% 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.
Something 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.
One of the first PRs I submit to a FOSS project I'm trying to contribute to, is usually their developer docs. It's only really new contributors to have to follow it and find all the undocumented assumptions.
If 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.
Yeah, I made this comment with that thought in mind! For all of SO's history I think it's safe to say they've been very generous (i.e. cognizant of what their platform offers/the potential risks of monetization in certain ways).
For what it's worth, I don't think Prosus will make a mistake in this way -- the fact that they've existed all this time without me (or most people, I think) ever hearing about them means that they are good at what they do. Regardless of what their main goals are, I assume that I'll think it's likely I continue to not hear about them.
A company that provides documentation that is complete and easy to use is a good company.
A company selling a product that requires the customer to search third party documentation for usage is a bad company.
For software tools, an educated customer is going to choose companies that have products that help solve their problems, not ones that add to them (in the form of more work to seek out out-of-band documentation).
The problem with many more niche things is that it hasn't gotten to the point where decent answers have accumulated on Google.
I recently had to build a Word Add-In. Not a lot of those built at the moment. So we were dependent on the documentation, which while reasonably comprehensive, had some frustrating gaps in just getting the tutorial code running that took days to resolve.
The new OfficeJS one. Try running the Angular tutorial in a desktop version of Word, which uses Legacy Edge/IE 11 as its runtime or at least did when we were doing this. It won't work.
Technical writer here. I avoid saying something is "simple," because whether it's simple is subjective and is relative to the reader's background knowledge. So at best it's unhelpful, and at worst it can be insulting.
If you're stuck on a task, the last thing you want to hear is that it's really simple.
On the other hand, I would write that X is a simpler approach than Y, if I was comparing two possible approaches.
It's not a good feeling when you find something "simple" to be hard. Few tasks are easy when you're a new programmer still wrapping your head around conditionals.
If my docs might be used by a new programmer I try to avoid alienating my users with the word simple.
When we say "simple", we use it as a way to say "not complex". If we want to say "not hard", we say "easy".
Words should be used carefully or we end up with no word to say what we mean. That's why there's literally no word meaning what we want to say by "literally".
But from context you can determine whether "literally" means "literally" or "figuratively". It's the same with "simple", you should assume it means "simple" and not "easy" in the case of a documentation where words are chosen carefully.
Right, 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.
The 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.
The problem for me is that it over-estimates my competence.
We've been told for years that it's demeaning to do the opposite and underestimate or over-explain, so people may have been erring too far in this direction.
We've also seen a lot of "the burden of communication lies on the communicator, not the listener," (quotes indicate paraphrasing) but this may also have led to overcorrection on the part of some listeners.
It's often impossible to predict what knowledge level and cultural background one's readers will have, so somehow we have to find a middle ground and ask that everyone mutually assume good faith and put in some effort to understand the other party, both when communicating and when reading.
I tried to just link to anything that might require more info. If you know how to do it, great, don't click the link. Otherwise, what you need is right there.
I think good documentation should help the user build a mental model. Keep explanations to the point in general, but insert short reminders about previous concepts (with cross-references to s detailed explanation) to keep them in the reader's mind. Some redundancy in documentation is a plus.
If you always include at least a summary of what the user is expected to know, it lets the user read the documentation nonlinearly without getting completely lost when they hit an unfamiliar concept.
I've found myself addressing the issue with a section at the top of documentation about the expected reader. I can get quite explicit about what the reader is expected to know, include links to relevant backgrounders, and warn that any reader who does not meet the requirements may have trouble.
This way, when someone ignores the section and comes to me in incomprehension of a document they were not expected to understand, I can ask them what was unclear about the "About This Document" section. Although that's probably optimistic about how often people read documentation.
I don't care if you call something simple, but I'd rather have you make it simple for me if you call it simple. Calling something simple can be a statement of fact ("objectively this thing is simpler than other comparable things") or it can be wishful thinking ("man this is really hard, better give them the motivation to wrap their head around it by taking away the edge"). The latter is what people tend to hate. It is "draw a circle, now draw the rest of the owl"-territory.
What I hate about this kind of bad documentation is that juat by spending an hour and writing down a few good examples and explaining them you could save hundreds of collective brain hours and maybe even improve adoption of your library if that is a relevant category for your project.
If you think writing down some good examples and explaining them takes "an hour", you have never written documentation. Writing good documentation takes forever!
Oh no worries I have written enough documentation. And you are right: writing good documentation is never done, because the thing you are documenting is never done and you can always fine tune the texts that you have written.
But more often than not you will find auto generated documentation where you see nothing on the first page, nothing explaining what that library can do, can't do, is intended to be used for, is not intended to be used for, some usage example how to get started etc.
Instead you will find a half page in some obscure class documentation that seems to be addressed to the dev themselves instead of to any outside audience.
What I mentioned above doesn't have to take long. You built the library. If you cannot write a simple example of how to use it within 5 minutes you probably should rewrite that library before publishing it. Integrate that example into your tests and now you even know when it will fail.
Serverless claims to be simple. But they don’t add “if you are building a toy project”. Therefore, it would be better if they just didn’t say it was simple at all.
They wouldn’t end up with bitter people writing warnings on HN 2 years after the fact.
The problem is that those marketing blurbs are never just on the front page these days, they're all through the documentation too. So I can't really fault people too much for falling for them.
I'm not sure if this is just a front-end JS thing or if everyone is having this problem, but it seems like the majority of people writing docs aren't doing it to educate their users, they're doing it to proclaim to the world how smart they are with their revolutionary new tool that "makes foo simple" (and by that they mean makes foo easier* by adding complexity), and if the person reading it happens to learn something too that's just a bonus.
*until you colour slightly outside the lines and have to dive into whatever their shit library abstracted away anyway.
In complex organizational environments managing complex technical landscapes, documentation using phrases that start with "simply..." are an indicator of insufficient technical writing fluency/structure/guidance/expectations.
In such a context, it is reasonable to expect documentation to have a lower and upper bound on detail and scope they cover. It is not reasonable to expect all readers to know how to bridge over out of bounds detail and/or scope if they need to for their particular use case.
Examples of operative phrases to use are "for more detail on..." or "for more information on...", the former letting readers know how to obtain prerequisite knowledge, the latter letting readers know how to obtain out of bounds perspectives. Unfortunately, the art of systems-thinking-grade (wonderful link to Russell Ackoff's article on the front page today) technical writing has greatly atrophied in practically all organizations I have consulted for, and deteriorated to tactical-level documentation that reinforces a downward spiral in systems comprehension capabilities across organizations. This stems largely from a global leadership culture that applies the "simply" or "just" mentality to technical writing (which IMHO really should be called "systems writing" when it reaches a certain complexity to point out what we're really trying to accomplish at that arguably different use case, using technical writing as a tiny subset of its value delivery).
It's similar to hearing someone say "um" or "like" a lot. It doesn't bother you much until you notice it, then you can't help but notice it all the time.
For me, "simply" and "just" are speed bumps in my reading. I notice them because they slow me down and serve no useful purpose in writing.
I've used a lot of systems/libraries/etc. which claim to be "simple", but are really anything but. In many cases, "simple" equals to "primitive", which means that as soon as I move beyond the five-line example from the README I'm very likely to stumble upon a problem which will easily take a couple of days of furious googling, code-reading and issue-creating to get around.
I don't think it's insulting my competence, it's just that "simple" is a sign that the original developer is not aware of the complexity (SNMP, anyone?) and hence it's now a trigger word for "prepare to be miserable for a while". And I don't like to feel miserable while dissecting something someone called "simple".
Yeah, communication is just about explaining what someone should understand. It's a simple concept, and as a result you can be sure that you only need to type a document once, and it's immediately understood. In fact, just like your comment, there isn't any way to misinterpret vague language, or have to cater to someone for whom English isn't their first language.
"Just" is a huge red-flag for me, not just in documentation, but also in effort estimation, requirements gathering, etc. It's the ??? between underpants gnomes and profit.
Personally, 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..."
I'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.
Me: 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?)
Sometimes 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.
"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.
I'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).
Another 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.
So 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 ;-)
FFT 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.
In 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.
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.
This 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.
This 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.
Years 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"
I 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.
That'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.
> 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.
If 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.
>> 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.
I 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.
Yeah - 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
> ...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.
I 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.
Personal 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.
I 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.
That'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.
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?"