Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Docs for Developers: An Engineer’s Field Guide to Technical Writing

apress.com

Post reply on HN
Print view View original

31–40 of 52 posts

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#31

Post by qbasic_forever »

mrwnmonm wrote: post #28
qbasic_forever wrote: post #12

Earlier quoted context omitted.

Docusaurus is a typical node-based SSG, you can easily run it on Netlify, Vercel, or other similar sites. They even have docs for how to do it: https://docusaurus.io/docs/deployment#deploying-to-netlify

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 back and edit and revise. You don't need to janitor or babysit a local install after the initial setup. Check out more info in some of their tutorials: https://www.netlify.com/blog/2016/09/29/a-step-by-step-guide...

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#32

Post by cratermoon »

macintux wrote: post #23
cratermoon wrote: post #2

I saw this book mentioned on twitter, the author(s) were hyping it. I'd love to buy the ebook but I don't want to have to register or accept any TOS, I just want to give money and download the epub format. Everywhere I've looked requires creating an account. I see it's available on Amazon but... well, I don't want Kindle format and also would prefer almost any other seller.

I've been quite happy to see Apple Pay spreading online, in part for that reason.

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.

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#33

Post by LeonB »

geomark wrote: post #29
hanswesterbeek wrote: post #8

Writing well is underrated. Too many people think they do it well. Kind of like Dutch people and their command of the English language.

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.

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#34

Post by detaro »

LeonB wrote: post #33
geomark wrote: post #29

Earlier 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.

While that plays a role, it's a bit odd to single out Dutch for that - far from the only European country where that is the case.

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#35

Post by tehnub »

teeray wrote: post #3

I do think clear writing is an indication of clear thinking, which leads to clear programming. However, technical writing is a real job with real work involved. To make developers write all the documentation is the same management mentality some places have about hiring “full-stack engineers.” The places I’ve worked at with truly excellent documentation had full-time technical writers that collaborated with engineers…

>[...] clear writing is an indication of clear thinking [...]

I think this is technically true, but I tend to think of it more like "Attempting to write clearly will lead to clear thinking". It's hard to be sure you're thinking clearly until you've attempted to communicate it precisely.

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#36

Post by infogulch »

I like linking to this site [0], the "The Grand Unified Theory of Documentation" that describes four categories of documentation that fill out a 2D space of potential docs value: the practical steps theoretical knowledge dimension, and the useful when studying useful when working dimension.

    * Tutorials - Learning-oriented -  (practical/studying)
    * How To Guides - Problem-oriented - (practical/working)
    * Explanations - Understanding-oriented - (theoretical/studying)
    * Reference - Information-oriented - (theoretical/working)
It passed through HN ~9 months ago [1], where kaycebasques stated, "I think the key breakthrough with Divio's framework is getting authors to think about docs in terms of desired goals and outcomes: learning-oriented, problem-oriented, etc."

[0]: https://documentation.divio.com

[1]: https://news.ycombinator.com/item?id=26002656

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#37

Post by jkbr »

kyleee wrote: post #20
jkbr wrote: post #16

Earlier quoted context omitted.

It’s a decoy. https://hstalks.com/t/3538/the-economist-a-pricing-experimen...

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?

What an interesting reaction.

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#38

Post by cratermoon »

qbasic_forever wrote: post #30
cratermoon wrote: post #26

Earlier quoted context omitted.

As best I can tell, and I'm willing to be proven wrong, to tell Netlify which static site generator to run, the configuration must specify the command. Unless Netlify is maintaining the version/container/build of whatever command is given, it's up to the site owner to provide that. Thus, it's on the site owner to specify a build command that doesn't introduce undesirable or malicious behavior.

It's a nodejs app using a standard package.json which captures all of the dependencies (including docusaurus version, etc.). Netlify detects the package.json, loads a container with node, installs the dependencies and goes to work. You don't need to manage anything. See more details: https://docs.netlify.com/configure-builds/manage-dependencie...

I don't see anything there that says Netlify is managing or maintaining the details. The customer provides the package.json, If that file contains a reference to a library or code that introduces bugs or vulnerabilities, it's on the customer. Thus it still puts the burden of maintenance on the customer.

In a managed SaaS installation, the customer would be paying for the functionality of, say, docusaurus, but the company would provide and maintain the dependencies. It's the difference between paying for a server to run a version of mysql you specify and paying a service to run mysql and keep it in a known good configuration while the customer is able to use mysql.

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#39

Post by DoingIsLearning »

detaro wrote: post #34
LeonB wrote: post #33

Earlier 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.

While that plays a role, it's a bit odd to single out Dutch for that - far from the only European country where that is the case.

Also a bit glossing over the details if we consider how close Dutch and English are compared with say Slavic languages and English or Latin languages and English.

I remember reading a while back that Old English and Old Frisian would have been mutually understandable. Although in fairness I doubt most Dutch today would follow a conversation in Frisian.

Re: Docs for Developers: An Engineer’s Field Guide to Technical Writing

#40

Post by pantulis »

cratermoon wrote: post #32
macintux wrote: post #23

Earlier quoted context omitted.

I've been quite happy to see Apple Pay spreading online, in part for that reason.

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.

Post reply on HN