[Maria-docs] Usage of an informal tone on the documentation on the KB
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?
On Thu, Jan 8, 2015 at 11:44 AM, Jean Weisbuch <jean@phpnet.org> 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
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 : maria-docs@lists.launchpad.net Unsubscribe : https://launchpad.net/~maria-docs More help : https://help.launchpad.net/ListHelp
participants (3)
-
Daniel Bartholomew -
Ian Gilfillan -
Jean Weisbuch