Pantheon Community

Making Contributing to Docs a Little Easier

The documentation team has made a few changes to the docs GitHub repo, that makes it a little easier for Pantheors and external contributors to create a docs issue.

What’s New:
We have disabled the option to open a blank issue, have created issue templates, and encourage docs contributors to choose from the templates provided. Now, when you click New Issue under the Issues tab, you can choose from creating an issue that requests new content, creating an issue to fix existing content, or selecting the option to just chat about docs issues.

Why:
The new templates allow us to streamline issue triaging and better identify how we can improve the Pantheon docs site. In the templates, specifications for labels, assignees, and projects are automatically applied, and the structure helps to pinpoint how the change will impact Pantheon users.

How:
To create the templates, we created and added content to the ISSUES_TEMPLATE folder . The template files are written in Markdown with a YAML formatter that specifies configurations. We customized the issue template chooser, by adding a config.yml file to the .github/ISSUE_TEMPLATE folder. If you are interested in viewing the code for our templates, please see our repo. You can also learn more about creating issue templates in GitHub via the UI, by reading this doc.

You can also always Report an issue or Edit a page directly from the Pantheon docs site pages.


Contributions to improve Pantheon documentation are welcome, encouraged, and greatly appreciated. We want the best documentation possible for our community! Every little bit helps and we recognize all of our amazing contributors.

For more information about contributing to Pantheon documentation, please see our contributing docs.

9 Likes

This is super cool @joan.edwards! Thanks for sharing these improvements here in our lil community. <3

2 Likes

Thanks Joan. I really like the new templates. I felt it was much clearer which parts I could edit. In the past I’ve gotten confused and tended to choose wrong on what example code I should remove or leave.

I felt the use of comments to guide me was great. Bonus points that I can leave them in but they don’t show. I hate when the guiding info is also the example text because I often delete it. Then I get half way through and want to reference it but it is now gone.

My one area of confusion was with choosing the right tag. I was unsure if the template chose the correct tag for me or if I needed to go through the list and choose one.

For instance I wanted to modify content and not create new content. I left it as the default (create new) since I didn’t see a modify option and assumed it covered both cases.

Hi @JohnRichardsII . Thanks so much for your great feedback; you make a great point. Would it be clearer if we created separate entries - one for “new” and the other for “changing”? Currently, we are grouping them together, and you are not required to choose one.

1 Like

I misread your response, so removing my previous message above.

I think it is fine as is. At most, you could put a comment that says the labels can be left alone.