update contributing guides

JonnyZockt · Aug 27, 2021 · 8405f00 · 8405f00
1 parent 5e40655
commit 8405f00
Show file tree

Hide file tree

Showing 7 changed files with 149 additions and 172 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/README.md b/README.md
@@ -4,46 +4,35 @@ This repository contains the documentation website code and Markdown source file
 
 GitHub's Docs team works on pre-production content in a private repo that regularly syncs with this public repo.
 
-In this article:
-
-- [Contributing](#contributing)
-- [READMEs](#readmes)
-- [License](#license)
+## Table of contents
 
+Use the table of contents icon <img src="./assets/images/table-of-contents.png" width="25" height="25" /> on the top left corner of the this document to get to a specific section of this guide quickly.
 ## Contributing
 
-### Start contributing right now:
-
-We accept a lot of [different contributions](CONTRIBUTING.md/#types-of-contributions-memo), including some that don't require you to write a single line of code.
+See our [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions of how to get started with our project. 
+<!-- info about codetour/codespaces (https://github.com/github/docs-team/issues/800) -->
 
-#### Click **make a contribution** from docs
+We accept different [types of contributions](CONTRIBUTING.md/#types-of-contributions-memo), including some that don't require you to write a single line of code.
 
-As you're using GitHub Docs, you may find something in an article that you'd like to add to, update, or change. Click on **make a contribution** to navigate directly to that article in the codebase, so that you can begin making your contribution.
+For quick fixes like typos, updates, link fixes etc., use **make a contribution** to make changes and submit a PR.
 
 <img src="./assets/images/contribution_cta.png" width="400">
 
-#### Open an issue
-
-If you've found a problem, you can open an issue using a [template](https://github.com/github/docs/issues/new/choose).
+**Open an issue** using an [issue template](https://github.com/github/docs/issues/new/choose).
 
-#### Solve an issue
+**Solve an issue** by first scanning through our [existing issues](https://github.com/github/docs/issues). When ready, check out [Getting Started with Contributing](/CONTRIBUTING.md) for detailed instructions.
 
-If you have a solution to one of the open issues, you will need to fork the repository and submit a pull request using the [template](https://github.com/github/docs/blob/main/CONTRIBUTING.md#pull-request-template) that is visible automatically in the pull request body. For more details about this process, please check out [Getting Started with Contributing](/CONTRIBUTING.md).
-
-#### Join us in discussions
+### Join us in discussions
 
 We use GitHub Discussions to talk about all sorts of topics related to documentation and this site. For example: if you'd like help troubleshooting a PR, have a great new idea, or want to share something amazing you've learned in our docs, join us in [discussions](https://github.com/github/docs/discussions).
 
-#### And that's it!
+### And that's it!
 
-That's how you can get started easily as a member of the GitHub Documentation community. :sparkles:
+If you're having trouble with your GitHub account, contact [Support](https://support.github.com/contact).
 
-If you want to know more, or you're making a more complex contribution, check out [Getting Started with Contributing](/CONTRIBUTING.md).
+That's how you can easily become a member of the GitHub Documentation community. :sparkles:
 
-There are a few more things to know when you're getting started with this repo:
-
-1. If you're having trouble with your GitHub account, contact [Support](https://support.github.com/contact).
-2. We do not accept pull requests for translated content - see [CONTRIBUTING.md](/CONTRIBUTING.md) for more information.
+If you want to know more, or you're making a more complex contribution, check out [Getting Started with Contributing](/CONTRIBUTING.md).
 
 ## READMEs
 
@@ -72,3 +61,7 @@ The GitHub product documentation in the assets, content, and data folders are li
 All other code in this repository is licensed under a [MIT license](LICENSE-CODE).
 
 When using the GitHub logos, be sure to follow the [GitHub logo guidelines](https://github.com/logos).
+
+## Thanks :purple_heart:
+
+Thanks for all your contributions and efforts towards the GitHub documentation. We thank you being part of our enormous community!!
diff --git a/assets/images/table-of-contents.png b/assets/images/table-of-contents.png
diff --git a/content/README.md b/content/README.md
@@ -20,23 +20,24 @@ See the [contributing docs](/CONTRIBUTING.md) for general information about work
   - [`showMiniToc`](#showminitoc)
   - [`miniTocMaxHeadingLevel`](#minitocmaxheadinglevel)
   - [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename)
+  - [`changelog`](#changelog)
   - [`defaultPlatform`](#defaultplatform)
   - [`defaultTool`](#defaulttool)
-  - [`learningTracks`](#learningTracks)
-  - [`includeGuides`](#includeGuides)
+  - [`learningTracks`](#learningtracks)
+  - [`includeGuides`](#includeguides)
   - [`type`](#type)
   - [`topics`](#topics)
   - [`contributor`](#contributor)
   - [Escaping single quotes](#escaping-single-quotes)
 - [Autogenerated mini TOCs](#autogenerated-mini-tocs)
 - [Versioning](#versioning)
-  - [Free-pro-team vs. GitHub.com versioning](#free-pro-team-vs.-github.com-versioning)
+  - [Free-pro-team vs. GitHub.com versioning](#free-pro-team-vs-githubcom-versioning)
 - [Filenames](#filenames)
 - [Whitespace control](#whitespace-control)
 - [Links and image paths](#links-and-image-paths)
   - [Preventing transformations](#preventing-transformations)
-- [Index pages](#index-pages)
-- [Creating new sublanding pages](#creating-new-sublanding-pages)
+  - [Index pages](#index-pages)
+  - [Creating new sublanding pages](#creating-new-sublanding-pages)
 
 ## Frontmatter
 
@@ -111,6 +112,12 @@ See [`contributing/redirects`](contributing/redirects.md) for more info.
 - Purpose: An abbreviated variant of the page title for use in breadcrumbs and navigation elements.
 - Type: `String`
 - Optional. If omitted, `title` will be used.
+
+|Article type   |Maximum character length |
+---  |  ---  |        
+|articles	     |     31 |
+|categories	  |27 |
+|map topics	  |30 |
 
 Example:
 

diff --git a/contributing/content-style-guide.md b/contributing/content-style-guide.md
@@ -31,6 +31,7 @@ These guidelines are specific to GitHub’s documentation. For general style que
 - [Reusables and variables](#reusables-and-variables)
 - [Tables](#tables)
 - [Titles](#titles)
+- [Short titles](#short-titles)
 - [User interface elements](#user-interface-elements)
   - [Boldface](#boldface)
   - [Branch names](#branch-names)
@@ -305,6 +306,20 @@ Use quotation marks around article titles, whether the article is hosted on GitH
 
 For further guidance, see “[Formatting titles](https://docs.microsoft.com/style-guide/text-formatting/formatting-titles)” in Microsoft’s Style Guide.
 
+## Short titles
+
+- Length should be 2-3 words.
+- Look contextually to see what to omit and how the full breadcrumb looks like.
+- Has to convey full meaning of the title and content of the category or map topic
+- :scissors: repeated words when possible
+- Short titles should be parallel to short titles for other similar content
+  - e.g. `Organizations and teams`, `Enterprise accounts`
+- Short titles should still mimic format of title
+  - For task-based titles, if there’s a preposition or object or it’s otherwise awkward to shorten, can use a noun sparingly, try to find a verb form
+  - e.g. Authenticating to GitHub :arrow_right: Authentication
+  - Installing and configuring GHE Server :arrow_right: Installation and configuration
+- Don’t introduce new words in short titles that aren’t in the full title
+
 ## User interface elements
 
 ### Boldface

diff --git a/contributing/how-to-use-labels.md b/contributing/how-to-use-labels.md
@@ -0,0 +1,6 @@
+### Labels
+Labels can help you find an issue you'd like to help with.
+- The [`help wanted` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) is for problems or updates that anyone in the community can start working on.
+- The [`good first issue` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) is for problems or updates we think are ideal for beginners.
+- The [`content` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Acontent) is for problems or updates in the content on docs.github.com. These will usually require some knowledge of Markdown.
+- The [`engineering` label](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Aengineering) is for problems or updates in the docs.github.com website. These will usually require some knowledge of JavaScript/Node.js or YAML to fix.
diff --git a/contributing/types-of-contributions.md b/contributing/types-of-contributions.md
@@ -0,0 +1,36 @@
+## Types of contributions :memo:
+You can contribute to the GitHub Docs content and site in several ways. This repo is a place to discuss and collaborate on docs.github.com! Our small, but mighty :muscle: docs team is maintaining this repo, to preserve our bandwidth, off topic conversations will be closed.
+
+### :mega: Discussions
+Discussions are where we have conversations.
+
+If you'd like help troubleshooting a docs PR you're working on, have a great new idea, or want to share something amazing you've learned in our docs, join us in [discussions](https://github.com/github/docs/discussions).
+
+### :beetle: Issues
+[Issues](https://docs.github.com/en/github/managing-your-work-on-github/about-issues) are used to track tasks that contributors can help with. If an issue has a triage label, we haven't reviewed it yet and you shouldn't begin work on it.
+
+If you've found something in the content or the website that should be updated, search open issues to see if someone else has reported the same thing. If it's something new, open an issue using a [template](https://github.com/github/docs/issues/new/choose). We'll use the issue to have a conversation about the problem you want to fix.
+
+### :hammer_and_wrench: Pull requests
+A [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) is a way to suggest changes in our repository.
+
+When we merge those changes, they should be deployed to the live site within 24 hours. :earth_africa: To learn more about opening a pull request in this repo, see [Opening a pull request](#opening-a-pull-request) below.
+
+We cannot accept contributions to the [REST API reference documentation](https://docs.github.com/en/rest/reference). If you spot an inaccuracy in the REST API reference documentation, open an issue in the [github/rest-api-description](https://github.com/github/rest-api-description/issues/new?template=schema-inaccuracy.md) repository.
+
+### :question: Support
+We are a small team working hard to keep up with the documentation demands of a continuously changing product. Unfortunately, we just can't help with support questions in this repository. If you are experiencing a problem with GitHub, unrelated to our documentation, please [contact GitHub Support directly](https://support.github.com/contact). Any issues, discussions, or pull requests opened here requesting support will be given information about how to contact GitHub Support, then closed and locked.
+
+If you're having trouble with your GitHub account, contact [Support](https://support.github.com/contact?tags=docs-contributing-guide).
+
+### :earth_asia: Translations
+
+This website is internationalized and available in multiple languages. The source content in this repository is written in English. We integrate with an external localization platform called [Crowdin](https://crowdin.com) and work with professional translators to localize the English content.
+
+**We do not currently accept contributions for translated content**, but we hope to in the future.
+
+### :balance_scale: Site Policy
+GitHub's site policies are published on docs.github.com, too!
+
+If you find a typo in the site policy section, you can open a pull request to fix it. For anything else, see [the CONTRIBUTING guide in the site-policy repo](https://github.com/github/site-policy/blob/main/CONTRIBUTING.md).
+