Lots of talk about documentation in this thread but returning to the book: has anyone read it or seen an independent review yet? I've seen the authors hyping its release; now I want to know if it's any good :)
Docs for Developers: An Engineer’s Field Guide to Technical Writing
41–50 of 52 posts
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#42Lots of talk about documentation in this thread but returning to the book: has anyone read it or seen an independent review yet? I've seen the authors hyping its release; now I want to know if it's any good :)
They are clearly so good at documentation that they link to a book rather than to a site with the actual docs.
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#43Earlier quoted context omitted.
Thanks for the reference. But if you would allow me to be honest, I don't want to even read that page. I have tons of things to do, I want to just write. I am using Gitbook right now but I like Docusaurus more. I hope if someone would enhance the design a little bit, and give me the ability to add custom CSS if I really wanted to. And I am happy to pay for it a reasonable price. I could actually just install it local…
Check out Netlify, I think you'd really like its build previews. Basically go through a teeny bit of pain once to set it up and then all you have to do is push updated documentation files to github. Netlify will detect the changed files, rebuild your site using docusaurus, and send you a URL to hit to immediately view the updated docs as a preview. If you like it you click a button and make it live, otherwise you go…
I will, thanks very much.
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#44Earlier quoted context omitted.
What's that about? I'm a native English speaker and know a few Dutch people but haven't noticed some effect like that.
Not the original commenter, but I’ve heard, and somewhat observed, that Dutch people are generally more fluent in English than other Europeans; and I’ve heard this attributed to Dutch television, where English shows are generally presented in English but with Dutch subtitles, unlike other European nations where such shows would be dubbed into the local language.
Mr. Westerbiek is saying that Dutch people think they're better at English than they generally are.
Or maybe I misunderstood that? I'm Dutch, so who knows...
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#45Question, which online documentation do you consider great?
I quite like the Stripe documentation and wished they open-sourced it. Any others?
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#46Earlier quoted context omitted.
That's an awful website you've linked; pop ups on popups, obscuring alerts, all overlaying the content. Do you mind providing a short text comment about what a "decoy" is in this context?
A Decoy is when you introduce an option in the menu that is "absurdly" or illogically priced, in order to make other options seem like a better deal. Some examples: - Some restaurant menus will have 1-2 incredibly expensive entrees or appetizers. They know the volume on these items will be low, but they make other items seem less expensive by comparison. - The most famous example is how the Economist did pricing for…
Thank you
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#47Earlier quoted context omitted.
Serious question, if you're going to hire people who are great technical writers, why would you have software developers (who are by definition not going to be as good TWs as the "real" TWs) also do it? You wouldn't expect TWs to dabble in the prod codebase.
> Serious question, if you're going to hire people who are great technical writers, why would you have software developers (who are by definition not going to be as good TWs as the "real" TWs) also do it? Software engineers are the SMEs whose knowledge TWs are trying to crystallize into documentation; them being disengaged from the documentation effort is the same problem as business SMEs being disengaged from the so…
Translation for people who are unfamiliar with the acronym: SME seems to stand for “subject matter expert.”
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#48Earlier quoted context omitted.
Apply Pay just shifts the registration and need to agree to a TOS to another party. Whatever happened to just "here's some cash money"? I've already got a bank account and credit cards, they already have my business. Just let me use them to buy your product.
The trick with Apple Pay is that supposedly you have already accepted Apple's TOS and they already have your cards so you do not need additional registrations. In Apple's grand, glorified vision that should be the only one you need.
How, exactly, is it that I've already accepted Apple's TOS? When did that happen? Why do they already have my cards?
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#49Earlier quoted context omitted.
The trick with Apple Pay is that supposedly you have already accepted Apple's TOS and they already have your cards so you do not need additional registrations. In Apple's grand, glorified vision that should be the only one you need.
How, exactly, is it that I've already accepted Apple's TOS? When did that happen? Why do they already have my cards?
Because to use Apple Pay you also need to have your cards in your Apple Wallet. Cant remember exactly the onboarding process for this but I guess there are a few checkboxes to check.
Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing
#50Earlier quoted context omitted.
Not the original commenter, but I’ve heard, and somewhat observed, that Dutch people are generally more fluent in English than other Europeans; and I’ve heard this attributed to Dutch television, where English shows are generally presented in English but with Dutch subtitles, unlike other European nations where such shows would be dubbed into the local language.
Mr. Westerbiek is saying that Dutch people think they're better at English than they generally are. Or maybe I misunderstood that? I'm Dutch, so who knows...
I re-read it and I think you’re right.