Skip to content

Create new API tutorial template

In the user research we did at the three Write the Docs conferences last year (see Template brainstorming report), many users identified the need for an API tutorial template.

Be aware that we already have:

For this project, it would be good to familiarize yourself with both the general tutorial template and the API reference template and make sure that you are designing a template that incorporates the best practices from these templates. We'd like these templates to harmonize with each other, with the API tutorial adding new insights that are specific to APIs.

Resources about this content type

During the research phase, it might help to look at examples of effective API tutorials (such as on sites like Stripe, which has a reputation for having high quality API documentation). Feel free to reach out to the authors of the other templates for advice as well.

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.
  • Editorial review phase - When your draft is in a state where you feel it is ready to get merged in, you can work with your working group lead to request an editorial team review. The template editorial team is composed of experienced members of the project who review your template project to ensure that it follows best practices for technical writing, has no major organization or structural issues, has no obvious gaps or missing content, is consistent with our style guide.
  • 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