Skip to main content

Edit documentation

Documentation plays a key role in making sure everyone has the information they need to use the design system, design, and implement code accordingly. We encourage you to contribute or update content in a few different ways.

Ways to edit content​

  1. Submit an issue proposing edits
  2. Edit content directly using the Github interface
  3. Develop on your local machine

Submit an issue​

We rely on you, the subject matter experts in the TELUS community to contribute to making these shared resources the best it can be, and that includes keeping the content up to date.

If you see anything missing, spot a typo, or have recommendations to improve the docs, please follow the process to submit an issue

Use the GitHub interface​

If you have the appropriate GitHub permissions to contribute to the Allium project, you can use GitHub's web interface for making changes directly into the repository. If you need help with getting the proper access to GitHub, send a message in the #ds-allium-support channel on Slack.

Edit a single file​

You can make changes to documentation using Github without having to write code.

  1. There are a couple of ways you can open the Github editor interface:
    1. Short way to edit a file
      1. Go to the page you want to edit
      2. Use the "Edit this page on Github" on the footer of the doc pages
    2. Long way to edit a file
      1. Head over to the Allium repository on GitHub
      2. View the source code by navigating to the code tab in the top navigation
      3. Go to the document you want to edit (for example, /packages/docs-allium/components/components/button.md)
      4. Click on the pencil icon to "Edit this file"
  2. Follow the guide on how to edit files in Github
  3. Continue to create pull request to submit your changes for review
    • Remember to add docs(ds-allium): to the beginning of the PR description so the intention of your changes are clear at a glance
  4. A core team member or trusted committer will merge your PR once you have the approval of two other developers

Edit multiple files​

It's likely you'll want to edit multiple files before submitting your pull request. Follow along to make edits to multiple files in Github:

  1. After your first commit and a new branch is created, don't continue to create pull request
  2. Continue editing more pages
    1. Go back to the root of the project by navigating to the code tab in the top navigation.
    2. Go to your branch using the link in the yellow notification and continue making changes
    3. Remember to describe your changes in the commit message when you commit changes
  3. When you're ready to submit all your changes, go back to the root of the project and use the compare & pull request button in the yellow notification
    1. Review all your edits and link to the edited files if further changes are required
  4. Continue to create pull request to submit your changes for review
    • Remember to add docs(docs-allium): to the beginning of the PR description so the intention of your changes are clear at a glance
  5. A core team member or trusted committer will merge your PR once you have the approval of two other developers

Local development​

If you're familiar with using Git, you may prefer to write content on your local machine using a text editor.

Before proceeding, make sure you check the Allium readme for the system requirements and make sure you have the required versions of the software installed on your machine.

Run the documentation site on your local machine:​

  1. Enter the directory where you'd like to save the project cd <your-directory>.
  2. Clone the repository git clone git@github.com:telus/allium-design-system.git.
  3. Enter the Allium directory cd allium-design-system.
  4. Run yarn in that directory.
  5. Enter the directory of the website you wish to run cd packages/docs-allium.
  6. Run yarn start, which will 'build' and then 'serve' the files locally. When this process is complete, it will display the URL you need to run in your browser. Changes will automatically reload in your browser.
  7. Follow the pull request process

Further resources​

We use Docusaurus to help create the Allium documentation site. Most of the documentation site and component pages are written in Markdown format. Check out these resources to help you: