>
> 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
