Skip to content

Contributing Content

Jump to bottom
Larah Armstrong edited this page Oct 12, 2022 · 14 revisions

Note: This content is not actively maintained. If you'd like us to maintain these guides, let us know by opening an issue.

Notice content missing and want to add more? Find an issue with typos or a code sample? Did you know you could edit and add pages using the GitHub website or by cloning the repo and submitting a PR?

Here's how!

Edit a page from website

On each webpage, you can select a link to edit the page. This link will open the correct page to edit, including versioned content!

  1. On a page you find an error, click the Edit this page link found at the bottom. The markdown file opens in GitHub.
  2. Make your edits to the file.
  3. Scroll to the bottom and select Create a new branch... Enter a name for the branch and click Propose Change.

  1. Submit a PR for the branch. We will review, provide feedback, and merge when complete.

Submit an issue

If you find an issue on a page, or want to request more information, submit an issue. You can enter issues through GitHub or directly as feedback per page using the Log an issue link found at the bottom. This also will note the version!

Add page using GitHub

If you do not want to clone a repo and work locally, you can add a page or edit directly through GitHub. To add a page:

  1. Open the correct folder depending on the docs and version. The Unity doc team can help put it in the correct place in your pull request (PR).

    • In development/Next release of docs: Use the docs folder.
    • Older version of docs: Open a product version folder located in this folder.
    • Release Notes: All release notes go in the releases folder
    • References: Doc templates, licenses, general references can go in the references folder

  2. Click Add File and select Create New File.

  3. Add a filename.md at the top.

  4. Copy, paste, and fill out the following in the first lines of your Markdown file:

---
id: installation
title: Installation
---
  1. Enter your content! See Working with Markdown for options and info.
  2. Enter a commit message and a name for your branch at the bottom of the GitHub page (Create a new branch for this commit and start a pull request. option).
  3. Create a PR request for your new branch. The Unity doc team will review, get your file in the navigation, and much more!

Clone the repo

  1. Fork and clone the repo using Git, GitHub Desktop, or other method.
  2. Create a branch from MASTER for your work.
  3. Commit updates to your branch and submit a Pull Request (PR).
  4. Unity developers, writers, and community members will review and provide feedback.

Docs Branching Strategy

Always branch from MASTER. The Unity Doc team uses two other branches with servers to test your work and provide previews.

Versions of content are based in FOLDERS not in BRANCHES. See About Versioning.

Write content and Templates

Edit existing markdown files or create new files for content:

  • Markdown (.md) content files are in /docs
  • Images (.png, .gif, .jpg) are in /static/img
  • Static downloadable files such as scripts can be saved in /static

🌟 TEMPLATES: Need a quick and easy way to write? Just copy the markdown content from this template file. Paste it into a new file, and write! All previews of templates are on the site.

Important: Make sure all file names are lowercase without spaces. This includes markdown, images, and downloaded files.

See Working with Markdown to learn more about creating files, using Markdown formats, adding images, adding navigation, and more.

Submit PR

Submit a PR for the branch. PRs use a template allowing you to select the type of change, enter the purpose and changes for the PR, and a link or number for an issue/ticket. This helps Unity review and prioritize reviews.

When complete, all PRs are reviewed, managed, and merged by Unity Technical Writers. We will expand to include maintainers as we grow.

Labels for PRs and issues

We'll add labels to your PRs to help get them reviewed and merged quickly as possible! Here's a guide and a link to the full list of labels.

Label Description
enhancement Site additions, plugins, development that aids in site generation, templates, and more
new content New topic markdown files for content, requires navigation additions
update Updates to existing content and files, typically does not require navigation updates
documentation New content, updates, any issues that affect documentation
type:feedback Feedback typically entered from the website "Log an issue" link from pages
type:feature Site additions, plugins, development that aids in site generation, templates, and more
type:bug Issues with content, the site, links, typos, etc
duplicate Closed issue due to duplicate issues/tickets, make sure to link to the original
question Some issues are simply questions on how things work or more information, if a question add this label
help wanted, good first issue Great issues for Community to claim and work on

Status labels:

Label Description
stat:awaiting response Waiting for response from the author of a PR
stat:awaiting triage Needs triaging from the docs team
stat:backlog Work moved to the backlog for future work
stat:committed Work has been triaged, considered, and accepted for work
stat:in consideration Internal Unity review and consideration of the work
stats:invalid, stat:wontfix Close the issue as unneeded, not verified, etc

Priority labels:

We will assign priority labels to best indicate highest to lowest importance for work. This will be initially determined with triage and updated as needed.

Unity Multiplayer Technology - Technical Docs

MTT Docs Wiki

Clone this wiki locally