Docs for Developers: An Engineer’s Field Guide to Technical Writing • Hacker News Board

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

#21

Post by clumsysmurf » Thu, Oct 21, 2021, 10:41 PM UTC

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…

I disagree. Documentation is about communication. How effective is an architect without communicating architecture?

If we consider a documentation system, maybe with guides, references, etc ... at minimum I would expect developers to clearly document APIs, database tables / schemas, contracts, and protocols.

A good example of developers not doing a good job here is the Android reference Javadocs... and I don't think this is the domain of technical writers.

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

#22

Post by qbasic_forever » Thu, Oct 21, 2021, 10:48 PM UTC

cratermoon wrote: post #18

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

Perhaps GP doesn't want to set up and maintain their own installation, which includes things like securing it and keeping the installation up-to-date with security patches and performance enhancements. It's completely reasonable to ask if someone is willing to provide it as a service and do the ops work in exchange for money. Saying "just install it here and run it yourself" strikes me as putting the burden on someon…

I think you should look into what Netlify actually does--you seem to be misunderstanding it as a typical hosted compute platform like EC2. With Netlify and similar service it's actually more like AWS lambda but tightly integrated into git/github. You push all your content source to github and setup a webhook that notifies Netlify of any change. Every time you commit Netlify will pull down your content, run your static site generator (docusaurus) in an ephermal container (like a lambda function) and then save the resulting generated content/HTML to their hosting site. At no time are you running or managing or operating an actual server.

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

#23

Post by macintux » Thu, Oct 21, 2021, 10:50 PM UTC

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.

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

#24

Post by jljljl » Thu, Oct 21, 2021, 11:08 PM UTC

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?

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 their online and print offerings -- The offered Online-only for $60, Print for $125, and Print + Online for $125. Obviously the Print-only option makes no sense, it's just there to make the Print + Online seem like a better deal, and push you away from the cheaper $60 offering. A less pop-up filled explanation is here: https://cxl.com/blog/pricing-experiments-you-might-not-know-...

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

#25

Post by RNCTX » Fri, Oct 22, 2021, 12:07 AM UTC

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 see it's available on Amazon but... well, I don't want Kindle format...

It's trivial to de-drm and convert a lot of ebooks.

You need Calibre (free/open source, gui [1]), its DeDrm plugin (free/open source, gui [2]), and its KindleUnpack plugin (free/open source, gui [3]). There's a guide [4], but the toolchain is all point/click, not a hassle at all to use.

> The DeDRM plugin handles books that use Amazon DRM, Adobe Digital Editions DRM (version 1), Barnes & Noble DRM, and some historical formats. The Obok plugin handles Kobo DRM.

For kindle books, it'll be less hassle over time if you install the Kindle app on your not-phone, not-tablet and just never update it. It'll just be a matter of import click + browse to the Kindle app's data folder and pick the most recent item after you buy one to instantly de-drm it and convert it to Epub. Amazon doesn't force upgrades of the app presently, and newer DRM schemes won't be pushed to you if your version doesn't support them.

1. https://calibre-ebook.com

2. https://github.com/apprenticeharper/DeDRM_tools/releases

3. https://github.com/dougmassay/kindleunpack-calibre-plugin/re...

4. https://www.epubor.com/free-kindle-drm-removal-calibre-plugi...

All of this is very well maintained and very well presented by the calibre community. Converting an Amazon format to Epub loses nothing in terms of functionality or aesthetics, the resulting Epubs in iBooks look identical to the drm versions on Kindle, and iBooks syncs notes/highlights across devices in non-drm Epubs just like Kindle does with its book formats (sans the public sharing of notes/highlights of course). The ability to embed your own metadata once the drm is gone is a nice plus as well.

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

#26

Post by cratermoon » Fri, Oct 22, 2021, 12:25 AM UTC

qbasic_forever wrote: post #22

cratermoon wrote: post #18

Earlier quoted context omitted.

Perhaps GP doesn't want to set up and maintain their own installation, which includes things like securing it and keeping the installation up-to-date with security patches and performance enhancements. It's completely reasonable to ask if someone is willing to provide it as a service and do the ops work in exchange for money. Saying "just install it here and run it yourself" strikes me as putting the burden on someon…

I think you should look into what Netlify actually does--you seem to be misunderstanding it as a typical hosted compute platform like EC2. With Netlify and similar service it's actually more like AWS lambda but tightly integrated into git/github. You push all your content source to github and setup a webhook that notifies Netlify of any change. Every time you commit Netlify will pull down your content, run your stati…

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.

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

#27

Post by cratermoon » Fri, Oct 22, 2021, 12:28 AM UTC

RNCTX wrote: post #25

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 see it's available on Amazon but... well, I don't want Kindle format... It's trivial to de-drm and convert a lot of ebooks. You need Calibre (free/open source, gui [1]), its DeDrm plugin (free/open source, gui [2]), and its KindleUnpack plugin (free/open source, gui [3]). There's a guide [4], but the toolchain is all point/click, not a hassle at all to use. > The DeDRM plugin handles books that use Amazon DRM, Ad…

I'm aware of all that and have been using Calibre for some time. That's not the solution I want to deal with. I would prefer to encourage authors and publishers to reduce friction for their potential readers and make their work available through less predatory means. Even though you and I may have the knowledge and ability to work through that friction, other people may not.

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

#28

Post by mrwnmonm » Fri, Oct 22, 2021, 12:42 AM UTC

qbasic_forever wrote: post #12

mrwnmonm wrote: post #9

Not very much off-topic, I wish someone makes https://docusaurus.io as a service.

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 locally, do whatever I want, generate the static files, and add it to my project. But I will have to maintain the installation (for a language that I don't use), keep it updated, maybe fight with npm for sometime, and also being familiar with Docusaurus itself.

And I prefer a service focused on this problem, than using a general (even if easier) solution like Netlify.

At the end of the day, I think I will do what you said, because that service doesn't exist now :)

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

#29

Post by geomark » Fri, Oct 22, 2021, 12:57 AM UTC

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.

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

#30

Post by qbasic_forever » Fri, Oct 22, 2021, 1:45 AM UTC

cratermoon wrote: post #26

qbasic_forever wrote: post #22

Earlier quoted context omitted.

I think you should look into what Netlify actually does--you seem to be misunderstanding it as a typical hosted compute platform like EC2. With Netlify and similar service it's actually more like AWS lambda but tightly integrated into git/github. You push all your content source to github and setup a webhook that notifies Netlify of any change. Every time you commit Netlify will pull down your content, run your stati…

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