Simplify guidelines documents

Question

Simplify guidelines documents

Closed this issue 6 years ago · 8 comments

There are three documents in total in the guidelines folder. outline.md works great an example_en-us.md is a nice example of what you want to get as a result, despite not all headlines have the same wording as the outline, so it's sometime easy to get lost for a moment.

I have a slightly mixed feeling about the third document styleguide_guidelines.md. Up to How to use these guidelines and including the text is great, but the rest is what we (should) have in the outline directly.

May I have a look and merge the chapters after How to use these guidelines from styleguide_guidelines.md to outline.md?

Tasks

Merge sections from styleguide_guidelines.md (Formality and Tone and below) to outline.md. Keep the most complete information from both.
Unify the headlines between outline.md and example_en-us.md.
Update the text of styleguide_guidelines.md to refer to both other documents.

Answer 1 · 2018-03-06T17:00:47.000Z

@mozilla-l10n/pm-group thoughts?

Answer 2 · 2018-03-06T17:13:16.000Z

Speaking about guidelines to make a style guide, there is still this document on MDN, which is the same text what was in here before #53 too. Is it still there on purpose? If not, we should replace the content on MDN with some text to bring people here.

Answer 3 · 2018-03-06T17:15:01.000Z

As far as I know, we'll need to remove anything that it's not related to Web Standards from MDN.

Answer 4 · 2018-03-06T23:22:34.000Z

I see what you mean Michal. It seems like most of this is otherwise just a repetition. I think you could merge the chapters after How to use these guidelines from styleguide_guidelines.md to outline.md - making sure to keep the most complete version each time.

I'll give some other @mozilla-l10n/pm-group the chance to chime in here though, in case I'm missing anything. Also, maybe good to have @unclenachoduh add his thoughts, in case there was a specific reason for doing this - and that I may have forgotten since last summer?

Answer 5 · 2018-03-06T23:53:50.000Z

These guidelines were originally meant to replace the MDN guidelines. I think that MDN page was supposed to come down at some point?

The original format of outline.md was a blank template and styleguide_guidelines.md contained the instructions for how to fill or adapt that template and descriptions of linguistic phenomena. When I first drafted the documents, I recognized that this format was potentially confusing. If it would be easier for translators if the information were consolidated into one document of instructions for writing a style guide, I think that should be done. The purpose of these documents is to make style guide creation easier for translators, not more difficult.

Answer 6 · 2018-03-07T17:58:08.000Z

Side note: @MikkCZ you mention that in example_en-us.md "not all headlines have the same wording as the outline, so it's sometime easy to get lost for a moment."
If it helps to align that wording, I think you can do that, too.

Answer 7 · 2018-03-07T18:41:51.000Z

sgtm :-) And yes, the MDN page is supposed to come down. That's on my (lengthy) to-do list.

…

On Wed, Mar 7, 2018 at 10:58 AM, Delphine Lebédel ***@***.***> wrote: Side note: @MikkCZ <https://github.com/mikkcz> you mention that in example_en-us.md "not all headlines have the same wording as the outline, so it's sometime easy to get lost for a moment." If it helps to align that wording, I think you can do that, too. — You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub <#89 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AB1yZIiEfJYO8FqPiETt5uXHwFgPidZXks5tcB-xgaJpZM4SfEOS> .

Answer 8 · 2018-03-08T06:56:29.000Z

Thanks for all the feedback. I take it as a green light to give it a try. However I won't have enough time to start before the weekend, so if anyone is interested in the issue before I start, s/he is free to take it.