News for hackers. Stuff that matters.
Re:The Surprising Power of Documentation by alexpotato on Monday June 12, 2023 @09:01AM (#36292746)
> You should write three types of documentation. One for users, one for admins and one about architecture.

I use an airplane analogy (different order than your three above):

1. "Congratulations on purchasing your 747"

2. "This is how you replace the auxiliary power unit"

3. "This is how you survive the engine catching fire"

Re:The Surprising Power of Documentation by remram on Monday June 12, 2023 @09:23AM (#36293004)
1 is not documenting anything, and both 1 and 3 are meant for pilots? Who are the "users" in this analogy?
Re:The Surprising Power of Documentation by nwatson on Monday June 12, 2023 @09:28AM (#36293081)
"1" is for the airline. What does purchasing the plane, or a fleet of such planes, mean to the company? What will be the benefits, duties, obligations wrt to the airplanes, at a high level?

Edit: word choice

Re:The Surprising Power of Documentation by JdeBP on Monday June 12, 2023 @10:13AM (#36293755)
On the contrary, 1 would be a "quickstart guide", a "welcome pack", or even just a "The first thing that you need to do to your new washing machine/jet aircraft is take the restraining bolts, used for immobilizing it during transport, off."