As a programmer I've realized that one of my special skills are that I read the docs. It's such an understated skill.
A big portion of learning embedded development is learning to read data sheets.
If someone’s having to read your docs, it’s not “simple”
111–120 of 146 posts
Re: If someone’s having to read your docs, it’s not “simple”
#11250% 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.
>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.
Re: If someone’s having to read your docs, it’s not “simple”
#113This 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.
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.
Re: If someone’s having to read your docs, it’s not “simple”
#11450% 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…
Bebelrc and friends are the worst offender.
Hard to reuse, confusing cascading config..
Re: If someone’s having to read your docs, it’s not “simple”
#115As a programmer I've realized that one of my special skills are that I read the docs. 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.
Re: If someone’s having to read your docs, it’s not “simple”
#116Personal 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.
Re: If someone’s having to read your docs, it’s not “simple”
#117Personal 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.
Re: If someone’s having to read your docs, it’s not “simple”
#118As a programmer I've realized that one of my special skills are that I read the docs. It's such an understated skill.
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.
Re: If someone’s having to read your docs, it’s not “simple”
#11950% 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.
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.
Re: If someone’s having to read your docs, it’s not “simple”
#120Earlier quoted context omitted.
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?
The same thing you do with your Word documents. NewNewMailSender. NewNewMailSenderFinal. NewNewMailSenderFinal2. NewNewMailSenderReallyFinal. And so on.
LatestNewCountdown2Final.docx