Style Guides on GitHub

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Style Guides on GitHub

Kekoa Riggin
When we began talking about style guides with localization communities at
l10n hackathons, we suggested that the Mozilla Wiki was a good place to
temporarily store them, until we could define a more centralized and
accessible place for them, and that that place would most likely be GitHub.
After a lot of research, we’ve created GitHub repository[1] to host all of
the Mozilla translation style guides, including community-specific ones.
Any style guide that is referenced on a team’s contact page has been copied
as a markdown file into this repository. The repository has been built with
Gitbooks [2] and the style guides can be accessed with greater readability
and improved search capabilities.

You may be wondering, “If the community style guides are already available
and linked on team contact pages, why do we need this GitHub repository?”
We understand this confusion and wish to address why the repository exists.

Recently, MDN underwent a major style and content change[3]. This meant
that the General Localization Style Guide that was available on MDN needed
to be assessed to determine what changes needed to be made or if MDN was
even a good home for it. After considering alternatives and associated
questions, such as “what about community-specific style guides”, we decided
that we need to build a place easy to find for all style guides. Having
this central repository for all style guides makes it easier to locate all
of the style guides that have been created by each community. We don’t want
the hard work to go to waste, that’s why we want to make these style guides
accessible and link to them from the team’s page in Pontoon. This
centralized repository helps us make sure we don’t miss any style guides.

Currently, community style guides are hosted on a variety of sources and in
a mix of formats. While this is not a problem in itself, these varied
formats and sources can make it difficult to locate the style guides.
Additionally, some of these sources stop hosting the style guide or the
style guide may become obsolete for whatever reason. This is not exclusive
to style guides hosted to non-Mozilla sources. The wiki at mozilla.org
doesn’t represent a good home for this data, for that reason we have moved
the General Localization Style Guide as well. Rather than lose the style
guides currently hosted on the Mozilla Wiki, we decided to make copies of
these style guides in the centralized GitHub Repository.

These considerations aren’t new—as you probably know from the past year’s
workshops—but they present an opportunity for us to make this change that
will facilitate quality assurance and accessibility for our translation
efforts.

This brings up a few tasks for language communities that have a style guide
or would like to add one to the repository:

   1. Please check that your current community style guide is in the
   repository[1] and that it is correct. It is possible that the style guide
   that was migrated to the repository is the wrong version or contains some
   errors from migration. If there are any errors in the style guide, please
   see number 2.
   2. If you need to update/correct or add a style guide to the repository,
   please update it in the GitHub repository. GitHub has instructions[4] on
   how to update a repository. Please follow these instructions to create a
   pull request. This pull request will be reviewed before being merged to the
   official style guides repository to try to maintain quality. In addition,
   each pull request should be reviewed by another member of the community as
   some of the repository administrators may not speak the language of the
   style guide.

If there are any questions regarding the new repository or community style
guides, please direct them to Kekoa [hidden email] or flod at
[hidden email].

[1] https://github.com/mozilla-l10n/styleguides
[2] https://mozilla-l10n.github.io/styleguides
[3] https://hacks.mozilla.org/2017/07/the-mdn-redesign-behind-the-scenes/
[4]
https://help.github.com/articles/editing-files-in-another-user-s-repository/
_______________________________________________
dev-l10n mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-l10n
Reply | Threaded
Open this post in threaded view
|

Re: Style Guides on GitHub

Michal Stanke-2
Hello Kekoa.

Thank you for all the clarifying information about the styleguides
repository. I have verified the Czech guides were moved completely and
added a link from the previous home to ensure, we keep this on one place.
Just a question, does the MDN change affect only styleguides, or all l10n
documents? Because I still see
https://developer.mozilla.org/en-US/docs/L10n_Style_Guide and
https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localizing_with_Pontoon
there, which I would personally classify as localizers docs.


--
Michal Stanke

2017-08-23 0:01 GMT+02:00 Kekoa Riggin <[hidden email]>:

> When we began talking about style guides with localization communities at
> l10n hackathons, we suggested that the Mozilla Wiki was a good place to
> temporarily store them, until we could define a more centralized and
> accessible place for them, and that that place would most likely be GitHub.
> After a lot of research, we’ve created GitHub repository[1] to host all of
> the Mozilla translation style guides, including community-specific ones.
> Any style guide that is referenced on a team’s contact page has been copied
> as a markdown file into this repository. The repository has been built with
> Gitbooks [2] and the style guides can be accessed with greater readability
> and improved search capabilities.
>
> You may be wondering, “If the community style guides are already available
> and linked on team contact pages, why do we need this GitHub repository?”
> We understand this confusion and wish to address why the repository exists.
>
> Recently, MDN underwent a major style and content change[3]. This meant
> that the General Localization Style Guide that was available on MDN needed
> to be assessed to determine what changes needed to be made or if MDN was
> even a good home for it. After considering alternatives and associated
> questions, such as “what about community-specific style guides”, we decided
> that we need to build a place easy to find for all style guides. Having
> this central repository for all style guides makes it easier to locate all
> of the style guides that have been created by each community. We don’t want
> the hard work to go to waste, that’s why we want to make these style guides
> accessible and link to them from the team’s page in Pontoon. This
> centralized repository helps us make sure we don’t miss any style guides.
>
> Currently, community style guides are hosted on a variety of sources and in
> a mix of formats. While this is not a problem in itself, these varied
> formats and sources can make it difficult to locate the style guides.
> Additionally, some of these sources stop hosting the style guide or the
> style guide may become obsolete for whatever reason. This is not exclusive
> to style guides hosted to non-Mozilla sources. The wiki at mozilla.org
> doesn’t represent a good home for this data, for that reason we have moved
> the General Localization Style Guide as well. Rather than lose the style
> guides currently hosted on the Mozilla Wiki, we decided to make copies of
> these style guides in the centralized GitHub Repository.
>
> These considerations aren’t new—as you probably know from the past year’s
> workshops—but they present an opportunity for us to make this change that
> will facilitate quality assurance and accessibility for our translation
> efforts.
>
> This brings up a few tasks for language communities that have a style guide
> or would like to add one to the repository:
>
>    1. Please check that your current community style guide is in the
>    repository[1] and that it is correct. It is possible that the style
> guide
>    that was migrated to the repository is the wrong version or contains
> some
>    errors from migration. If there are any errors in the style guide,
> please
>    see number 2.
>    2. If you need to update/correct or add a style guide to the repository,
>    please update it in the GitHub repository. GitHub has instructions[4] on
>    how to update a repository. Please follow these instructions to create a
>    pull request. This pull request will be reviewed before being merged to
> the
>    official style guides repository to try to maintain quality. In
> addition,
>    each pull request should be reviewed by another member of the community
> as
>    some of the repository administrators may not speak the language of the
>    style guide.
>
> If there are any questions regarding the new repository or community style
> guides, please direct them to Kekoa [hidden email] or flod at
> [hidden email].
>
> [1] https://github.com/mozilla-l10n/styleguides
> [2] https://mozilla-l10n.github.io/styleguides
> [3] https://hacks.mozilla.org/2017/07/the-mdn-redesign-behind-the-scenes/
> [4]
> https://help.github.com/articles/editing-files-in-
> another-user-s-repository/
> _______________________________________________
> dev-l10n mailing list
> [hidden email]
> https://lists.mozilla.org/listinfo/dev-l10n
>
_______________________________________________
dev-l10n mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-l10n
Reply | Threaded
Open this post in threaded view
|

Re: Style Guides on GitHub

Jeff Beatty
Good question, we're in the process of migrating all relevant MDN docs into
GitHub/GitBook. We haven't yet asked MDN to take those pages down yet.

Thanks,
Jeff

El 22 ago. 2017 11:41 PM, "Michal Stanke" <[hidden email]> escribió:

> Hello Kekoa.
>
> Thank you for all the clarifying information about the styleguides
> repository. I have verified the Czech guides were moved completely and
> added a link from the previous home to ensure, we keep this on one place.
> Just a question, does the MDN change affect only styleguides, or all l10n
> documents? Because I still see
> https://developer.mozilla.org/en-US/docs/L10n_Style_Guide and
> https://developer.mozilla.org/en-US/docs/Mozilla/
> Localization/Localizing_with_Pontoon
> there, which I would personally classify as localizers docs.
>
>
> --
> Michal Stanke
>
> 2017-08-23 0:01 GMT+02:00 Kekoa Riggin <[hidden email]>:
>
> > When we began talking about style guides with localization communities at
> > l10n hackathons, we suggested that the Mozilla Wiki was a good place to
> > temporarily store them, until we could define a more centralized and
> > accessible place for them, and that that place would most likely be
> GitHub.
> > After a lot of research, we’ve created GitHub repository[1] to host all
> of
> > the Mozilla translation style guides, including community-specific ones.
> > Any style guide that is referenced on a team’s contact page has been
> copied
> > as a markdown file into this repository. The repository has been built
> with
> > Gitbooks [2] and the style guides can be accessed with greater
> readability
> > and improved search capabilities.
> >
> > You may be wondering, “If the community style guides are already
> available
> > and linked on team contact pages, why do we need this GitHub repository?”
> > We understand this confusion and wish to address why the repository
> exists.
> >
> > Recently, MDN underwent a major style and content change[3]. This meant
> > that the General Localization Style Guide that was available on MDN
> needed
> > to be assessed to determine what changes needed to be made or if MDN was
> > even a good home for it. After considering alternatives and associated
> > questions, such as “what about community-specific style guides”, we
> decided
> > that we need to build a place easy to find for all style guides. Having
> > this central repository for all style guides makes it easier to locate
> all
> > of the style guides that have been created by each community. We don’t
> want
> > the hard work to go to waste, that’s why we want to make these style
> guides
> > accessible and link to them from the team’s page in Pontoon. This
> > centralized repository helps us make sure we don’t miss any style guides.
> >
> > Currently, community style guides are hosted on a variety of sources and
> in
> > a mix of formats. While this is not a problem in itself, these varied
> > formats and sources can make it difficult to locate the style guides.
> > Additionally, some of these sources stop hosting the style guide or the
> > style guide may become obsolete for whatever reason. This is not
> exclusive
> > to style guides hosted to non-Mozilla sources. The wiki at mozilla.org
> > doesn’t represent a good home for this data, for that reason we have
> moved
> > the General Localization Style Guide as well. Rather than lose the style
> > guides currently hosted on the Mozilla Wiki, we decided to make copies of
> > these style guides in the centralized GitHub Repository.
> >
> > These considerations aren’t new—as you probably know from the past year’s
> > workshops—but they present an opportunity for us to make this change that
> > will facilitate quality assurance and accessibility for our translation
> > efforts.
> >
> > This brings up a few tasks for language communities that have a style
> guide
> > or would like to add one to the repository:
> >
> >    1. Please check that your current community style guide is in the
> >    repository[1] and that it is correct. It is possible that the style
> > guide
> >    that was migrated to the repository is the wrong version or contains
> > some
> >    errors from migration. If there are any errors in the style guide,
> > please
> >    see number 2.
> >    2. If you need to update/correct or add a style guide to the
> repository,
> >    please update it in the GitHub repository. GitHub has instructions[4]
> on
> >    how to update a repository. Please follow these instructions to
> create a
> >    pull request. This pull request will be reviewed before being merged
> to
> > the
> >    official style guides repository to try to maintain quality. In
> > addition,
> >    each pull request should be reviewed by another member of the
> community
> > as
> >    some of the repository administrators may not speak the language of
> the
> >    style guide.
> >
> > If there are any questions regarding the new repository or community
> style
> > guides, please direct them to Kekoa [hidden email] or flod at
> > [hidden email].
> >
> > [1] https://github.com/mozilla-l10n/styleguides
> > [2] https://mozilla-l10n.github.io/styleguides
> > [3] https://hacks.mozilla.org/2017/07/the-mdn-redesign-
> behind-the-scenes/
> > [4]
> > https://help.github.com/articles/editing-files-in-
> > another-user-s-repository/
> > _______________________________________________
> > dev-l10n mailing list
> > [hidden email]
> > https://lists.mozilla.org/listinfo/dev-l10n
> >
> _______________________________________________
> dev-l10n mailing list
> [hidden email]
> https://lists.mozilla.org/listinfo/dev-l10n
>
_______________________________________________
dev-l10n mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-l10n