Re: readability changes to postgres.sgml - Mailing list pgsql-docs

From Liudmila Mantrova
Subject Re: readability changes to postgres.sgml
Date
Msg-id CAEkD-mC4uq9a_yO+OSdkJVG2FZHh2KrqQSXkSxFaTQHD+fRFLw@mail.gmail.com
Whole thread Raw
In response to Re: readability changes to postgres.sgml  (Erik Rijkers <er@xs4all.nl>)
Responses Re: readability changes to postgres.sgml  ("Joshua D. Drake" <jd@commandprompt.com>)
List pgsql-docs


For what it's worth, I think the proposed changes are all solid
improvements. The text reads better with them, and that's what this is
about -- not whether the removed little text-pieces were 'true' or not.


I'm afraid I can't agree that all changes are good enough (e.g. "start with describing the general syntax of <acronym>SQL</acronym>, then how to create tables.." used to be better with a verb, and "Readers are encouraged review" is probably too liberal grammar). Changes like "encouraged to look" vs. the original "should see" can be also challenged as an improvement - IMHO the original version reads equally well (although it could be more concise for sure).

That said, I agree we should not hold on to every word just because it was written - the shorter the docs, the more chances they get to be actually read. Avoiding assumptions about what's simple may also be beneficial. A simple concept for one can be new and unclear to another, no matter how experienced they actually are.

If we want to make these intros more concise, one of the easiest ways to achieve this is to address the reader directly ("Readers looking for xxx are encouraged to look" vs. smth like "For xxx, see"). We can also question the need for some of the provided info - for example, assumptions about typical user behavior and complexity of the text that follows could probably be let gone altogether. I don't believe they can actually guide anyone as they are quite vague anyway (how many are "the first few" chapters exactly?) That would leave us with the scope of the chapters described and explicit references to elsewhere (if required for clarity), making the most valuable parts here more prominent and not-so-easy to skip.


--
Best regards,
Liudmila Mantrova 

Technical writer at Postgres Professional: http://www.postgrespro.com

pgsql-docs by date:

Previous
From: Tom Lane
Date:
Subject: Re: Wrong drop procedure example
Next
From: Erik Rijkers
Date:
Subject: Re: readability changes to postgres.sgml