On Fri, Jul 20, 2018 at 05:31:40PM -0700, Adrian Klaver wrote: > JD sit down, I am going to agree with you:) The documentation as it stands > is very good, though it requires some fore knowledge to successfully > navigate. On pages with a lot of content it often is not evident, to many, > that there are actually examples at the bottom of the page. Also that the > exceptions to the rules are called out there also. The general concept of > presenting a task, writing a procedure to accomplish the task and pointing > to the documentation that covers the procedure would be a helpful addition. > It would be nice to point to something like that in a post rather then > continually rebuilding the explanation every time a new user hits the list. > Looking at the link posted upstream: I am jumping in late here, but I do have some thoughts on this topic. To me, there are three levels of information presentation: 1. Task-oriented documents 2. Exhaustive technical documentation/manuals 3. Concept-level material I think we call agree that the Postgres documentation does very well with #2, and we regularly get complements for its quality. For #1, this is usually related to performing a task without requiring a full study of the topic. For example, if I need iptables rules to block a sunrpc attack, or use NFS over ssh, I really want some commands that I can study and adjust to the task --- I don't want to study all the features of these utilities to get the job done. This is an area the docs don't cover well, but our blogs and wikis do. For #3, this is mostly covered by books. This topic requires a lot of explanation and high-level thinking. We have some of that in our docs, but in general books probably do this better. -- Bruce Momjian <bruce@xxxxxxxxxx> http://momjian.us EnterpriseDB http://enterprisedb.com + As you are, so once was I. As I am, so you will be. + + Ancient Roman grave inscription +
