4 ms·

It’s funny how you just can’t win with documentation: either “there is no documentation” or “tl;dr”

BigJono 3y ago
Surely if there's anything you don't need a 'tl;dr' for it's setting up your database backups lol. I just had a quick skim of those docs, looks like lots of paragraphs going over all of all the things that can go wrong and how to prevent them. Good. If it takes a week to read all that and set up then it takes a week. I'll take a pass on the "docker container that just does it for me" thanks.
quest88 3y ago
Queue the future “show hn: a lightweight pg backup solution”
stavros 3y ago
In your opinion the two choices are "no documentation" and "badly-written documentation"?
- dspillett 3y ago
  Long does not imply bad at all, unless the tl:dr; is in response to it being a badly structured wall of text. I've not read that page from end to end, only scanned through it, but it seems perfectly good for covering the concept, with one caveat that it might not include a detail I'd put in there. Unless I missed it in my scan the page may be missing a point that seems obvious but relatively green admins might miss until they run it of backup space (or start getting larger bills for the auto-growing cloud storage they are backing up to!): your WAL based backups will grow infinitely, and restore time will grow likewise, if you don't occasionally restart your backup sequence with a fresh full backup.
  - stavros 3y ago
    > unless the tl:dr; is in response to it being a badly structured wall of text. It is, yes. It does contain a lot of information, but the fact that it's one big wall of text makes my ADHD go do something else. Even a table of contents, or some better-structured headlines would help.
    - rafaelmn 3y ago
      Plop it into a LLM and ask it to summarize with references or reformat to your preference. GPT3.5-turbo does a decent job and you can always refer to original source with references.
      - stavros 3y ago
        That's a good idea, thanks! I might even resubmit that as a PR.
- abenga 3y ago
  "Badly written" is something I have never heard about official Postgres documentation.
- fiddlerwoaroof 3y ago
  No, whatever you do about documentation, people will either complain that you didn’t write it or they will complain that they don’t have the time to read it. This is true regardless of how good the documentation you write is.

Surely if there's anything you don't need a 'tl;dr' for it's setting up your database backups lol. I just had a quick skim of those docs, looks like lots of paragraphs going over all of all the things that can go wrong and how to prevent them. Good. If it takes a week to read all that and set up then it takes a week. I'll take a pass on the "docker container that just does it for me" thanks.

quest88 3y ago

Queue the future “show hn: a lightweight pg backup solution”

stavros 3y ago

In your opinion the two choices are "no documentation" and "badly-written documentation"?

dspillett 3y ago
Long does not imply bad at all, unless the tl:dr; is in response to it being a badly structured wall of text. I've not read that page from end to end, only scanned through it, but it seems perfectly good for covering the concept, with one caveat that it might not include a detail I'd put in there. Unless I missed it in my scan the page may be missing a point that seems obvious but relatively green admins might miss until they run it of backup space (or start getting larger bills for the auto-growing cloud storage they are backing up to!): your WAL based backups will grow infinitely, and restore time will grow likewise, if you don't occasionally restart your backup sequence with a fresh full backup.
- stavros 3y ago
  > unless the tl:dr; is in response to it being a badly structured wall of text. It is, yes. It does contain a lot of information, but the fact that it's one big wall of text makes my ADHD go do something else. Even a table of contents, or some better-structured headlines would help.
  - rafaelmn 3y ago
    Plop it into a LLM and ask it to summarize with references or reformat to your preference. GPT3.5-turbo does a decent job and you can always refer to original source with references.
    - stavros 3y ago
      That's a good idea, thanks! I might even resubmit that as a PR.
abenga 3y ago
"Badly written" is something I have never heard about official Postgres documentation.
fiddlerwoaroof 3y ago
No, whatever you do about documentation, people will either complain that you didn’t write it or they will complain that they don’t have the time to read it. This is true regardless of how good the documentation you write is.