4 ms·

Another good example is the differences in the documentation for Indexes, vs the https://use-the-index-luke.com/ https://use-the-index-luke.com/ that explains m

Another good example is the differences in the documentation for Indexes, vs the https://use-the-index-luke.com/ https://use-the-index-luke.com/ that explains many of the reasons WHY you want to organize it with great examples. A problem I have is so many tutorials, or 'best practices' I find on the internet are for older versions that don't really apply as well in newer versions of postgres. Like searching for logical replication, you find lots of information for pg_logical for older versions of postgres, but many of those parts are now baked into postgres, but with a different syntax, etc. I would love to see a 'tutorials/guide' and 'best practices' part of the documentation that is updated with each new release, that give examples of the most common tasks, and when/why to use them, and when to move to something more advanced. Some really basic stuff like "this is the 3 best ways to handle replication in version 15, and the 2 or 3 most common ways to do backups, or these are the recommended ways to migrate from the previous version either in place, or to a new server, etc.

starkparker 3y ago
> I would love to see a 'tutorials/guide' and 'best practices' part of the documentation that is updated with each new release, that give examples of the most common tasks, and when/why to use them, and when to move to something more advanced. Tutorials and best practices come about from real-world usage, which is why they're often out of date — by the time someone becomes enough of an expert on features specific to a version to write good-quality content of that nature, a new version is out. The only way to update those is through real-world usage, which means shipping pre-release versions for long-enough periods of time and having them used to ship real things, all before the release. Does PostgreSQL do this? It hasn't in my experience, but it's admittedly limited to the last 5-6 years.
friendzis 3y ago
> Like searching for logical replication, you find lots of information for pg_logical for older versions of postgres, but many of those parts are now baked into postgres, but with a different syntax, etc. I tend to see this as duality of static/ephemeral. On one hand you have "vendors" treating software as rolling moving target - latest and greatest is all there is. On the other hand, there are community guides and tutorials that are out there and never retracted or amended. Let's say I find an article that luckily states being written against older version of software. How do I know whether the information is still valid and applicable to a newer version? Well, if I am lucky and the vendor publishes growing changelog I have to read it and judge of the changes are applicable. Maybe I have to hunt down changelogs from all the interim versions just to see if anything important to me changed. Most probably I will find a very succinct summary of the change like "toll x was merged into tool y" or "updated interface of x". Now I have to try and find the discussion around the change in mailing lists (hopefully the team has not migrated to Discord). Contrast this with hardware. Quite possibly I will find erratas and/or product change notices discussing the changes, maybe even application guides discussing how to apply changes. Unless there is an entirely new product line being released there is high change there will be rather detailed documentation on changes. Software is usually majorly lacking in this regard. And no, versioned documentation is not the answer. Documentation gets updated not only technically, but also as discussed structurally. Once a piece of documentation gets moved to another section or even reworded I can no longer reasonably search for changes. Documentation of a changing, evolving thing is hard and interestingly this is where open source gets hit the most - there are almost no incentives for someone to write good documentation.

starkparker 3y ago

> I would love to see a 'tutorials/guide' and 'best practices' part of the documentation that is updated with each new release, that give examples of the most common tasks, and when/why to use them, and when to move to something more advanced. Tutorials and best practices come about from real-world usage, which is why they're often out of date — by the time someone becomes enough of an expert on features specific to a version to write good-quality content of that nature, a new version is out. The only way to update those is through real-world usage, which means shipping pre-release versions for long-enough periods of time and having them used to ship real things, all before the release. Does PostgreSQL do this? It hasn't in my experience, but it's admittedly limited to the last 5-6 years.

friendzis 3y ago

> Like searching for logical replication, you find lots of information for pg_logical for older versions of postgres, but many of those parts are now baked into postgres, but with a different syntax, etc. I tend to see this as duality of static/ephemeral. On one hand you have "vendors" treating software as rolling moving target - latest and greatest is all there is. On the other hand, there are community guides and tutorials that are out there and never retracted or amended. Let's say I find an article that luckily states being written against older version of software. How do I know whether the information is still valid and applicable to a newer version? Well, if I am lucky and the vendor publishes growing changelog I have to read it and judge of the changes are applicable. Maybe I have to hunt down changelogs from all the interim versions just to see if anything important to me changed. Most probably I will find a very succinct summary of the change like "toll x was merged into tool y" or "updated interface of x". Now I have to try and find the discussion around the change in mailing lists (hopefully the team has not migrated to Discord). Contrast this with hardware. Quite possibly I will find erratas and/or product change notices discussing the changes, maybe even application guides discussing how to apply changes. Unless there is an entirely new product line being released there is high change there will be rather detailed documentation on changes. Software is usually majorly lacking in this regard. And no, versioned documentation is not the answer. Documentation gets updated not only technically, but also as discussed structurally. Once a piece of documentation gets moved to another section or even reworded I can no longer reasonably search for changes. Documentation of a changing, evolving thing is hard and interestingly this is where open source gets hit the most - there are almost no incentives for someone to write good documentation.