I've also toyed with writing a style guide, but for now it remains in my
head. Now that I know someone has been looking, I may start to put some
of it down!
The tone in the KB is not overly formal, which in English I think this
is a positive and helps readability, especially since many readers are
not first-language speakers. The use of the word "you" I'm happy with,
for example, "If you see error X, you may need to do Y" is fine.
The use of the word "I" I've tended to rewrite when coming across it, as
I don't think this reads well. Quite a lot of the documentation though
has been written by a developer explaining a feature they've developed
or tested, and the older documentation especially hasn't always been
closely looked at.
If you have specific examples you think may be too informal, or come
across the word "I", send the links through to me and I'll take a look.
I second Daniel that when translating to French, feel free to adjust the
tone as required.
ian
On 01/08/2015 06:44 PM, Jean Weisbuch 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?
_______________________________________________
Mailing list: https://launchpad.net/~maria-docs
Post to : [email protected]
Unsubscribe : https://launchpad.net/~maria-docs
More help : https://help.launchpad.net/ListHelp
_______________________________________________
Mailing list: https://launchpad.net/~maria-docs
Post to : [email protected]
Unsubscribe : https://launchpad.net/~maria-docs
More help : https://help.launchpad.net/ListHelp
