On Thu, Dec 17, 2020 at 7:42 AM Bruce Momjian wrote:
> I agree a holistic review of the docs can yield great benefits. No one
> usually complains about overly verbose text, but making it clearer is
> always a win. Anyway, of course, it is going to be very specific for
> each case. As an extreme
On Mon, Dec 14, 2020 at 01:38:05PM -0800, Peter Geoghegan wrote:
> On Mon, Dec 14, 2020 at 12:50 PM Tom Lane wrote:
> > Most of the docs contain pretty dense technical
> > material that's not going to be improved by making it even denser.
>
> It's always hard to write dense technical prose, for
>
>
>
> > Queries can also access multiple tables at once, or access the same table
> > in a way that multiple rows are processed. A query that accesses multiple
> > rows of the same or different tables at one time is a join. For example,
> if
> > you wish to list all of the weather records with th
Joshua Drake writes:
> Certainly and I didn't want to just start dumping patches. Part of this is
> just style, for example:
> Thus far, our queries have only accessed one table at a time. Queries can
> access multiple tables at once, or access the same table in such a way that
> multiple rows of
On Mon, Dec 14, 2020 at 12:50 PM Tom Lane wrote:
> Most of the docs contain pretty dense technical
> material that's not going to be improved by making it even denser.
It's always hard to write dense technical prose, for a variety of
reasons. I often struggle with framing. For example I seem to
>
>
>
> In short, the devil's in the details. Maybe there are lots of
> places where this type of approach would help, but I think it's
> going to be a case-by-case discussion not something where there's
> a clear win overall.
>
Certainly and I didn't want to just start dumping patches. Part of t
On Mon, Dec 14, 2020 at 1:40 PM Joshua Drake wrote:
> For example, what would be exceedly helpful would be a documentation style
>>> guide that is canonical and we can review documentation against.
>>>
>>
I do agree with that premise, with the goal of getting more people to
contribute to writing
Heikki Linnakangas writes:
> On 14/12/2020 21:50, Joshua Drake wrote:
>> Issues that are resolved with the optimized text:
>>
>> * Succinct text is more likely to be read than skimmed
>>
>> * Removal of extraneous mentions of PostgreSQL
>>
>> * Removal of unneeded justifications
>>
>> * Joinin
>
>
>
> > This is the official PostgreSQL documentation. It is written by the
> > PostgreSQL community in parallel with the development of the software.
> > We have organized it by the type of user and their stages of experience:
>
> Some thoughts on this example:
>
> - Changing "has been" to "is"
>
>
>>
>> Technical documentation should only be as verbose as needed to illustrate
>> the concept or task that we are explaining. It should not be redundant, nor
>> should it use .50 cent words when a .10 cent word would suffice. I would
>> like to put effort into optimizing the documentation and
On 14/12/2020 21:50, Joshua Drake wrote:
The community has spent a lot of time optimizing features over the
years. Excellent examples include parallel query and partitioning which
have been multi-year efforts to increase the quality, performance, and
extend features of the original commit. We
On Mon, Dec 14, 2020 at 12:50 PM Joshua Drake wrote:
> -hackers,
>
> The community has spent a lot of time optimizing features over the years.
> Excellent examples include parallel query and partitioning which have been
> multi-year efforts to increase the quality, performance, and extend
> feat
12 matches
Mail list logo
