[cfe-dev] [PATCH] LibTooling docs

[James K. Lowden]

On Fri, 20 Apr 2012 10:30:55 +0200
Manuel Klimek <klimek at google.com> wrote:

> > But better: "Once the CompilationDatabase
> > is created, ...."
> 
> Again, my strong preference for active voice trumps the idea of more
> formality.

If I could chime in here, I want to suggest that the passive is
sometimes better, depending on the focus.  (If you want to spend an
afternoon reading about the relatively recent, and strictly American,
indictment of the passive, I'd be happy to provide references.)  

One reason the passive is adopted is to disguise agency.  It leads to
lazy constructions.  The K-12 writer is taught not to use the passive in
part because the formation permits not saying what he doesn't know.
"Rome was invaded in 256 AD."  

In the earlier example: 

>  "To that end we create a CompilationDatabase."

the agent matters: "we" set about creating the database over the course
of the next ~5 paragraphs.  ("is needed" might be better if it
continued to explain by what or for what, if that mattered.)  

When that's done, 

> > Once the CompilationDatabase is created,

agency is uninteresting, and "we" don't matter anymore.  We're off to
the next thing.  

Subject is topic: what matters isn't that we created the database
(aren't we great?) but that the database has been created (yay!).  

> I disagree with the idea that we need to be overly formal in those
> tutorials. Now, if you think that some of my bad grammar makes the
> sentences hard to understand / read, I'm happy to change

Quite.  Pedantic rules will not great writing make.  

Style manuals disagree on the use of contractions.  Let us look forward
to the day when the best way to improve our documentation is to choose
between "can't" and "cannot". 

--jkl