If someone’s having to read your docs, it’s not “simple”(justsimply.dev)
justsimply.dev
If someone’s having to read your docs, it’s not “simple”
https://justsimply.dev
145 comments
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.
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 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()).
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()).
Ha, I edited my comment to say the same thing before I noticed yours. Couldn't agree more.
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.
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.
The word “just” is superfluous in the sentence, and to the author’s point can easily imply more simplicity in use, concepts, etc. than is warranted.
Software documentation should be more like scientific article writing: passive, and having few or no modifiers like “trivial” or “just” or the like.
Software documentation should be more like scientific article writing: passive, and having few or no modifiers like “trivial” or “just” or the like.
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.
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"
"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"
The context of this is the Action Mailer Guide:
https://guides.rubyonrails.org/v4.2.0/action_mailer_basics.h...
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.)
https://guides.rubyonrails.org/v4.2.0/action_mailer_basics.h...
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.)
To me, both sentences make it seem like I really want to render a view, and Mailers are one possible way.
Perhaps a more effective edit would just use controllers as an analogy from the beginning instead of focusing on views.
> Mailers are like controllers, but for email instead of HTTP.
Perhaps a more effective edit would just use controllers as an analogy from the beginning instead of focusing on views.
> Mailers are like controllers, but for email instead of HTTP.
> Does this change destroy the meaning of the sentence?
Edited that for you.
Edited that for you.
It’s really just you. Or it’s just you. Either way, it’s you.
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.
As a programmer I've realized that one of my special skills are that I read the docs.
It's such an understated skill.
It's such an understated skill.
I just wish many of the docs were better.
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.
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.
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.
That's just lazy javadoc style. The worst kind of documentation, since it adds nothing over looking at code itself.
At the very least, there should be examples of usage.
I never did PHP, but they have one of the best documentation features: comments. It allows you to recognize if a function is a footgun: https://www.php.net/manual/en/function.utf8-decode.php
At the very least, there should be examples of usage.
I never did PHP, but they have one of the best documentation features: comments. It allows you to recognize if a function is a footgun: https://www.php.net/manual/en/function.utf8-decode.php
There is a difference between documentation and tutorials.
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.
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.
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.
This 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…
Lol, as if that’s an easy or trivial thing…
A big portion of learning embedded development is learning to read data sheets.
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?
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
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 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've had a handful of developers do this, mostly in frontend work with lifecycles because they didn't read
how fast though ? I've read emacs manual. over 20 years :) (and in 3-4 passes)
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.
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.
I think you're getting downvoted because none of what you mentioned isn't docs. You do read them, you just read a specific type of documentation.
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.
Not sure about the percentage but plenty are from people that don't even bother to read what is available or buy a book!
They just do stack overflow driven programming, question & paste.
They just do stack overflow driven programming, question & paste.
[deleted]
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.
> the documentation was not great in the first place
or a pain to find when searching online in the first place...
or a pain to find when searching online in the first place...
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.
Looks like GitHub is already getting ahead of this with the "Discussions" feature.
> If Stack Overflow ever changes their model/tries too hard to monetize
On that subject, Stack Overflow was just acquired for $1.8 billion.
On that subject, Stack Overflow was just acquired for $1.8 billion.
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.
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.
>If someone’s having to read your docs, it’s not “simple”
If it's actually not a simple subject or process, don't shortcut on the documentation.
If it's actually not a simple subject or process, don't shortcut on the documentation.
It's gotten to a point where if I run into an issue, my first instinct is to go to the source code instead of the docs.
Someone who solves problems by Googling is a good customer.
Someone who needs handholding or is unsophisticated is a bad customer.
For developer tools and such, an educated person’s game, the sophisticated players will have better LTV than the unsophisticated ones.
Someone who needs handholding or is unsophisticated is a bad customer.
For developer tools and such, an educated person’s game, the sophisticated players will have better LTV than the unsophisticated ones.
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).
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).
Being able to function without good documentation is not the same as thinking that it is a good idea. One is a useful skill, the other is idiocy.
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.
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.
OfficeJS Add-In or the old one?
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.
This 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.
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.
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.
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.
Simple is the opposite of complex, not the opposite of hard. Saying something is simple has meaning, and it's not insulting.
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.
If my docs might be used by a new programmer I try to avoid alienating my users with the word simple.
The real question and a better post than the original post would be: Are people living in the 21st Century too easily offended?
But it's a rhetorical question...
But it's a rhetorical question...
> Simple is ... not the opposite of hard.
...yes it is? The word has multiple meanings.
> free from complexity or difficulty [https://www.merriam-webster.com/dictionary/simple]
> involving minimal difficulty or effort [https://www.merriam-webster.com/thesaurus/simple]
etc
...yes it is? The word has multiple meanings.
> free from complexity or difficulty [https://www.merriam-webster.com/dictionary/simple]
> involving minimal difficulty or effort [https://www.merriam-webster.com/thesaurus/simple]
etc
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.
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.
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.
It is bad writing style as well. Streamlining the narrative in your tutorial and avoiding unnecessary words decreases the mental load of the reader.
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.
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.
My solution to that is just an abundance of links.
Here is a tutorial I wrote:
https://dev.to/mattgaiser/how-to-debug-an-office-js-manifest...
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.
Here is a tutorial I wrote:
https://dev.to/mattgaiser/how-to-debug-an-office-js-manifest...
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.
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.
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.
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.
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.
They wouldn’t end up with bitter people writing warnings on HN 2 years after the fact.
Meh. If someone just blindly believes some marketing blurb and ignore the blitheringly obvious challenges, isn't that at least a little on them?
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.
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.
Sure, perhaps. But people who make marketing content that contains bullshit or dishonesty shouldn’t get a free pass.
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).
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.
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.
They convey relative difficulty. It's good to know what the simple operations are.
Basically.
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".
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.
"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?)
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.
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.
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.
Another 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?
For example, class names "MailSender" and then you add "NewMailSender". What do you call it when the "NewMailSender" is old?
The same thing you do with your Word documents.
NewNewMailSender. NewNewMailSenderFinal. NewNewMailSenderFinal2. NewNewMailSenderReallyFinal. And so on.
NewNewMailSender. NewNewMailSenderFinal. NewNewMailSenderFinal2. NewNewMailSenderReallyFinal. And so on.
Also, it's always relative.
Agreed. Same thing with "Smart".
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.
Subtly Monitoring At RunTime
Ditto "better", "simple", and "[yet] another".
Is 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].
Wow 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 ;)
Also, I find it hilarious that you have an entire website dedicated to make your point. I would give a +2 for that ;)
OP here: many thanks for my +2!
Or 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.
There is a tendency to actually document the first point of contact with code, but nothing after that.
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.
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.
Another word I often see riddled in our code base is "Obviously". It might be obvious to the original author ... but not the reader.
Well it conveys the information: no further documentation on this available anywhere
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'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.
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.
Brought to you by "just simply dot dev"
I believe that is the point?
Yeah, sorry, I wasn't being sarcastically ironic or anything.
I agree for the most part. However, IMHO using these words (just, simply, etc) occasionally can make the doc more lively and fun to read.
Do 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".
I'm having a hard time understanding how such language would make documentation more "lively and fun to read".
> 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.
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.
"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.
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 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
Totally agree: that's the other website from us that didn't make it to Hacker News today https://dayofcode.co.uk
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.
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.
Do not use adverbs in technical writing period
"not" is an adverb. I don't know how you'd go about avoiding it.
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 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 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."
I can't quantify it, but I saw the title and thought, "GOSH yes. I HATE those kinds of docs."
Possibly 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/
… 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/
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.
> 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.
> That’s better: cleaner, less cluttered and less, frankly, infuriating.
They should add "frankly" to the list.
They should add "frankly" to the list.
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.
The 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.
To your point - I would argue that passive voice is more appropriate for documentation, and active for tutorials.
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.
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.
[deleted]
If someone's having to read your docs, it's not discoverable. It may well be simple to do once you know.
[deleted]
This blog is again hard to read.
[deleted]
I've found it less complex to just read GCP's SDKs and API libraries source code than to read the documentation.
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.
People getting offended just because someone said something is easy and simple. Problems of the 21's century...
id recommend focusing on documentation that goes through much more complex layers than fussing over this.
And he's also misreading what simple means.
And he's also misreading what simple means.
*she
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?"