Re: Optimizing the documentation

>
>
>
> > 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 the location of the
> > associated city, we would compare the city column of each row of the
> weather
> > table with the name column of all rows in the cities table, and select
> the
> > rows *WHERE* the values match.
>
> TBH, I'm not sure that that is an improvement at all. I'm constantly
> reminded that for many of our users, English is not their first language.
> A little bit of redundancy in wording is often helpful for them.
>

Interesting point, it is certainly true that many of our users are ESL
folks. I would expect a succinct version to be easier to understand but I
have no idea.

>
> The places where I think the docs need help tend to be places where
> assorted people have added information over time, such that there's
> not a consistent style throughout a section; or maybe the information
> could be presented in a better order. We don't need to be taking a
> hacksaw to text that's perfectly clear as it stands.
>

The term perfectly clear is part of the problem I am trying to address. I
can pick and pull at the documentation all day long and show things that
are not perfectly clear. They are clear to you, myself and I imagine most
of the readers on this list. Generally speaking we are not the target of
the documentation and we may easily get pulled into the "good enough" when
in reality it could be so much better. I have gotten so used to our
documentation that I literally skip over unneeded words to get to the
answer I am looking for. I don't think that is the target we want to hit.

Wouldn't we want the least amount of mental energy to understand the
concept as possible for the reader? Every extra word that isn't needed,
every extra adjective, repeated term or "very unique" that exists is extra
energy spent to understand what the writer is trying to say. That mental
energy can be exhausted quickly, especially when considering dense
technical topics.

> (If I were thinking of rewriting this text, I'd probably think of
> removing the references to self-joins and covering that topic
> in a separate para. But that's because self-joins aren't basic
> usage, not because I think the text is unreadable.)
>

That makes sense. I was just taking the direct approach of making existing
content better as an example. I would agree with your assessment if it were
to be submitted as a patch.

> > The reason I bolded and capitalized WHERE was to provide a visual signal
> to
> > the example that is on the page.
>
> IMO, typographical tricks are not something to lean on heavily.
>

Fair enough.

JD