Skip to content

Rework API quickstart template

We have an existing API quickstart template, but it is old and a little state. It needs to be reworked and improved to meet our current quality standards.

To improve this template, a templateer needs to be familiar with our current template standards and evaluate how close this template is to meeting those standards. The templateer should also research best practices about API quickstarts and review several high-quality examples of this content type in action to see how the template could be improved.

Link to Google Doc drafts

Our project composes rough draft of templates in Google Docs that are owned and maintained by the project leads. The Good Docs Project owns these files so that we can maintain our project archive and history. With that in mind, the project has pre-generated Google Doc files for you to use as you are researching and drafting your template project. These files include a starting point for the structure of each file that should help you as you draft the documents:

Bookmark these drafts and use them as you work on your project.

See the next section for more information about these files.

Definition of done

A template project is considered complete when it has progressed through all the template writing phases and when it has all the required template file deliverables.

Template writing phases

To be considered complete, a template project must progress through each template writing phase:

  • Research phase - When you first start a template project, you begin by researching examples and best practices for that template project. This phase ends when you create your resources document for that template.
  • Rough draft phase - After you conclude your research, you create drafts of your template file deliverables in Google Docs. This phase ends when you schedule your drafts for review by other members of your working group or community.
  • Community review phase - When your template project is ready for review, your working group lead will schedule 1-2 sessions in the community where other members of the project will review and provide feedback on your template files deliverables. This phase ends after you incorporate the feedback into your draft and your drafts are in a final state.
  • Final review phase - When your template is in a final state, you convert it from Google Docs into Markdown and open a merge request to add your template to the templates repository. The template leads will review the template and possibly request additional changes. This phase ends when the template is merged into the repository.

After the final review phase, the template project is considered done. However, be aware that after it is merged, the template then goes to the Chronologue working group for testing. They will make a high quality example of the template and they may make additional changes to the template to improve its usability.

See the Templates CONTRIBUTING guide for guidance about these phases. You can also receive help from your working group leads and members about how to move your template project through each phase.

Required template deliverables

To be considered complete, a template project must have the following four files:

  • Template file - The raw template for the content type.
  • Template guide - Provides a deeper explanation of how to fill in the template.
  • Template resources - Includes the resources consulted during the research phase of creating the template. Also includes high quality examples of that content type that served as inspiration for the template.
  • Template process - Explains best practices for researching, writing, and maintaining this content type.

After a template project is complete, our Chronologue working group will create an example of the template.

See the Template deliverables guide for guidance about these files. You can also look at examples of other templates in the repository to see examples of each template file. Be aware that some templates might be missing some files.

Want to work on this template?

Great! Make sure you follow our contributing guidelines:

  1. Check that the template is unassigned. If it is assigned, you might be able to work with the current assignee as a paired writer.
  2. Join The Good Docs Project by attending a Welcome Wagon meeting. You will get access to The Good Docs Project Slack workspace after scheduling or attending this meeting.
  3. Read the Templates CONTRIBUTING guide.
  4. You are strongly encouraged to join one of the working groups to get valuable support from the community such as mentorship, Git training, and helpful feedback as you contribute to your first template.
  5. Request access to the templates repository by joining the #tech-requests channel in Slack and posting a request.
  6. Assign yourself to an issue for the template that you want to work on.
  7. Add the Template phase:: Research label to the issue.
  8. Attend your template working group regularly to receive support and resources for your project.
Edited by Alyssa Rock