maria-docs team mailing list archive

[Daniel Bartholomew <dbart@xxxxxxxxxxx>]

On Thu, Jan 8, 2015 at 11:44 AM, Jean Weisbuch <jean@xxxxxxxxxx> wrote:
> There are no details about what tone should be used on the KB pages
> (https://mariadb.com/kb/en/meta/contributing-to-the-mariadb-knowledge-base/
> ) and many of the KB pages use an informal/personal tone with the use of the
> first (i, we) and second person (you) which i think doesn't suit very well
> for a enterprise-grade product documentation, at least it doesn't feels
> right when translating pages to French.
>
> Is that intentional or not and should there be a rule about that at least on
> documentation pages?

There's no hard and fast rule, and nothing documented. I've had
various conversations over the years about creating a style guide for
the KB, but they never got to the point where anything was written
down.

I'm personally not opposed to the use of an informal tone, or a formal
tone for that matter as long as it doesn't get too stuffy or academic.
My own feeling is that documentation should be "useful and friendly",
but how to achieve that is open to interpretation and I know others
have different priorities for what docs should be and look like. It is
also very possible to take casualness and informality too far and
imagine there are pages in the KB where that is the case and they
should be cleaned up or rewritten.

If you feel the French translation would be improved by adopting a
more formal tone, by all means do so.

Thanks!

-- 
Daniel Bartholomew, MariaDB Release Manager
MariaDB | http://mariadb.com