Skip to content
This repository has been archived by the owner on Sep 24, 2022. It is now read-only.

Added README template and template guide for review #248

Open
wants to merge 1 commit into
base: dev
Choose a base branch
from

Conversation

fungjoanne
Copy link

@fungjoanne fungjoanne commented May 26, 2022

Template quality checklist

This quality checklist will eventually become a pull request template that every contributor needs to add to pull requests against the templates repository.

Pull request summary

{Describe the purpose of your pull request.}

{Also indicate which template working group you belong to and who your template mentor is.}

Template contributor checklist

IMPORTANT: The next three sections in this checklist should be filled out by the template contributor at the time they submit this request.

NOTE: Pull requests can only be merged when all boxes are checked.

Which issue does this pull request fix or reference?

This pull request:

  • Resolves: {Choose this option if this PR will close the issue and link to issue}
  • Relates to: {Choose this option if this PR only references an issue for context but does not fully resolve it}

Procedural requirements

  • The template contributor participated in a template working group to create this template.
  • This template was submitted to the community for feedback.
  • A template mentor approved this template set to move to the pull request phase.

Template set requirements

  • Template file is present.
  • Template guide is present.
  • Template deep dive is present (optional).
  • Template example is present (optional).
  • If the optional template example is not present, open a new issue to track this task in the Chronologue repository, then include the link here.

Template pull request reviewer checklist

IMPORTANT: The rest of the sections in this checklist should only be filled out by authorized Good Docs Project pull request reviewers. If you are the individual template contributor, do not fill out the rest of the fields or check the boxes.

NOTE: Pull requests can only be merged when all boxes are checked.

Mechanics and formatting requirements - PULL REQUEST REVIEWER ONLY

  • Check rendered Markdown output to ensure it renders correctly.
  • Review the template set to ensure all documents follow the template markdown style guide.
  • The template set is free from grammar errors and typos.

Overall usability - PULL REQUEST REVIEWER ONLY

  • The scope of the template set is appropriate, meaning it is not too simple or overly complex (i.e. it needs to be expanded or broken into multiple smaller templates).
  • The template is complete and comprehensive.
  • The template set is well-organized and the contents flow in a logical order.
  • The template is well-written and clear.
  • The template set provides sufficient guidance about how to fill it in and implement the template in a documentation project.

Template file requirements - PULL REQUEST REVIEWER ONLY

  • Check rendered Markdown output to ensure it renders correctly and follows the template markdown style guide.
  • The template title is present and is an H1.
  • The template includes an introductory comment mentioning the other template resources (such as the guide).
  • Embedded writing tips are formatted with {curly brackets}.
  • The template is free from grammar errors and typos.
  • The scope of the template is appropriate, meaning it is not too simple or overly complex (i.e. it needs to be expanded or broken into multiple smaller templates).
  • The template is complete and comprehensive.
  • The template is well-organized and the contents flow in a logical order.
  • The template is well-written and clear.

Template guide requirements - PULL REQUEST REVIEWER ONLY

  • Check rendered Markdown output to ensure it renders correctly and follows the template markdown style guide.
  • The template guide title is present and is an H1.
  • The template includes an introductory comment pointing them to other template resources.
  • Embedded writing tips are formatted with {curly brackets}.
  • The template guide is free from grammar errors and typos.
  • The template guide includes a "Why do I need this type of document?" section.
  • The template guide includes a "Contents of this template" section.
  • The contents listed in the "Contents of this template" section mirror the sections in the raw template.
  • The template guide includes an implementation checklist (optional).
  • The template guide includes additional resources (optional).
  • The template guide is well-organized and the contents flow in a logical order.
  • The template guide is well-written, clear, and provides sound advice to template users.

Deep dive requirements (optional) - PULL REQUEST REVIEWER ONLY

  • Check rendered Markdown output to ensure it renders correctly and follows the template markdown style guide.
  • The deep drive title is present and is an H1.
  • The deep dive guide provides helpful advice about necessary requirements for writing this type of documentation.
  • The template set is well-organized and the contents flow in a logical order.
  • The template is well-written and clear.

Template example requirements (optional) - PULL REQUEST REVIEWER ONLY

  • Check rendered Markdown output to ensure it renders correctly and follows the template markdown style guide.
  • The template example provided is well-written and provides a clear example of how to use the template.

Copy link
Contributor

@barbaricyawps barbaricyawps left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI, I leave feedback using the Conventional Comments method: https://conventionalcomments.org/

Praise: Joann, this whole template is AMAZING already! I have a few suggestions, but so much of this is really strong as it is. Very, very nice work!

readme/template-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
readme/template-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
readme/template-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
readme/template-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
readme/template-readme.md Show resolved Hide resolved
Copy link

@Hdeshynska93 Hdeshynska93 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Editorial change

readme/template-readme.md Show resolved Hide resolved
Copy link

@soliloquizin soliloquizin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great template (and guide), very helpful!

readme/template-guide-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
readme/template-readme.md Show resolved Hide resolved
readme/template-readme.md Show resolved Hide resolved
readme/template-readme.md Show resolved Hide resolved
readme/template-readme.md Show resolved Hide resolved
readme/template-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
Copy link

@anaradujko anaradujko left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

readme/template-guide-readme.md Show resolved Hide resolved
readme/template-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
readme/template-guide-readme.md Show resolved Hide resolved
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants