Skip to content

Commit 722ee9e

Browse files
bcbogdanbcbogdan
authored
Merge pull request #891 from supertokens/add-templates
Add several templatess that can be used when writing docs
2 parents ab98f65 + 15c246f commit 722ee9e

File tree

5 files changed

+339
-15
lines changed

5 files changed

+339
-15
lines changed

‎.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,21 @@
11
## Summary of change
2+
23
(A few sentences about this PR)
34

45
## Related issues
6+
57
- Link to issue1 here
68
- Link to issue1 here
79

810
## Checklist
11+
912
- [ ] Algolia search needs to be updated? (If there is a new sub docs project, then yes)
1013
- [ ] Sitemap needs to be updated? (If there is a new sub docs project, then yes)
11-
- [ ] Checked for broken links? (Run `cd v2 && MODE=production npx docusaurus build`)
14+
- [ ] Checked for broken links? (Run `cd v3 && npm run build`)
1215
- [ ] Changes required to the demo apps corresponding to the docs?
1316

1417
## Remaining TODOs for this PR
18+
1519
- [ ] Item1
16-
- [ ] Item2
20+
- [ ] Item2
21+

‎.github/workflows/versioning.yml

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎v3/templates/api-reference.md

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# API Reference template
2+
3+
> The following template is taken from [The Good Docs Project](https://www.thegooddocsproject.dev/template/api-reference)
4+
> Some adjustments/clarifications have been made in the context of the **SuperTokens** docs.
5+
6+
## Overview
7+
8+
Use the {product} APIs to {access | customize | program} the {features | functionality}.
9+
10+
### Base URL
11+
12+
```text
13+
{Provide the base URL of the API. For example: https://api.example.com}
14+
```
15+
16+
### Authorization
17+
18+
Authentication and authorization {is | is not} required for requests to these APIs. Supported authentication methods are:
19+
{ Basic | Digest | OAuth | others}
20+
21+
```text
22+
{Provide an example request with {Basic | Digest | OAuth | others} authentication.}
23+
```
24+
25+
### Version
26+
27+
{This section is optional.}
28+
29+
{Provide the version number using semantic versioning or your product's API versioning scheme. For example: `0.0.1`}
30+
31+
### Pagination
32+
33+
{This section is optional.}
34+
35+
Due to the potentially very large result sets from API calls, responses {are | can be} returned as shorter pages.
36+
37+
Pagination can be customized using {pagination settings}. If not specified, the default values are {values}.
38+
39+
### Rate limiting and throttling
40+
41+
{This section is optional.}
42+
43+
The {product} APIs use a {strategy-name} rate limiting strategy. The maximum number of requests allowed to access a {resource | endpoint |..} is {number} requests per {time period}.
44+
45+
### HTTP status codes
46+
47+
The {product} APIs use the following standard HTTP response codes:
48+
49+
| Status code | Message | Description |
50+
| ----------- | ----------------- | ------------- |
51+
| `200 OK` | Request succeeds. | {description} |
52+
| | | |
53+
| | | |
54+
55+
### Errors
56+
57+
{This section is optional.}
58+
59+
The {product} APIs use the following error types:
60+
61+
| Error | Description |
62+
| --------------------------------------- | ---------------- |
63+
| [{ExampleErrorType}](#exampleerrortype) | {Failure in ...} |
64+
| | |
65+
| | |
66+
67+
#### ExampleErrorType
68+
69+
| Field | Type | Description |
70+
| -------------- | -------- | -------------------------------------------------------------------- |
71+
| {errorType} | {enum} | {Predefined error codes. Possible enum values are x, y, ..., and z.} |
72+
| {errorMessage} | {string} | {Additional information about why the error occurs.} |
73+
74+
## {Resource name}
75+
76+
The {resource name} is used to {functionality}.
77+
78+
### Data model
79+
80+
| Attribute | Type | Required? | Description |
81+
| --------- | ------ | --------- | --------------------------- |
82+
| {id} | string | Required | {Unique identifier of user} |
83+
| {name} | string | Optional | {Name of user} |
84+
| | | | |
85+
86+
### Example
87+
88+
```text
89+
{Provide an example of the data representation in the format that your project use.}
90+
```
91+
92+
### Endpoints
93+
94+
Use the following endpoints to interact with the {resource name} entities.
95+
96+
| Method | Endpoint name | Description |
97+
| ------ | ---------------------------------------- | ----------------------- |
98+
| POST | {[Endpoint name A](#link_to_endpoint_a)} | Creates a {resource}. |
99+
| GET | {[Endpoint name B](#link_to_endpoint_b)} | Retrieves a {resource}. |
100+
| | | |
101+
102+
## {Endpoint name}
103+
104+
{Provide a one-line description of what the API does. Starts with a verb in the indicative mood. For example, "Retrieves a user by `userID`".}
105+
106+
### Endpoint
107+
108+
```text
109+
{METHOD} /{request-url}/{{path-parameter}}
110+
```
111+
112+
### Description
113+
114+
{Explain what the endpoint does.}
115+
116+
{This paragraph is optional.} This endpoint has been deprecated. Use {the recommended endpoint} instead. For more information about how to migrate to {the recommended endpoint}, see [{the migration guide}](#link).
117+
118+
{This paragraph is optional.} The maximum number of calls to this API endpoint is {number} per minute. For more information about API rate limiting/throttling, see [{the topic}](#example).
119+
120+
### Authorization
121+
122+
The [{authorization method}](#authorization) is required for each API request.
123+
124+
{This paragraph is optional.} Calling this endpoint also requires the {permission-name} permission.
125+
126+
### Request schema
127+
128+
#### Path parameters
129+
130+
{This section is optional.}
131+
132+
| Path parameter | Type | Required? | Description |
133+
| -------------- | ------ | --------- | --------------------------- |
134+
| {id} | string | Required | {Unique identifier of user} |
135+
| | | | |
136+
137+
#### Query parameters
138+
139+
{This section is optional.}
140+
141+
| Query parameter | Type | Required? | Description |
142+
| --------------- | ---- | --------- | --------------------------------------------------------------------------------- |
143+
| {pageSize} | int | Optional | {The number of items to be returned in a single request. The default value is N.} |
144+
| | | | |
145+
146+
#### Header parameters
147+
148+
{This section is optional.}
149+
150+
| Header parameter | Type | Required? | Description |
151+
| ---------------- | ------ | --------- | ------------------------------------------------ |
152+
| {Content-Type} | string | Required | {Media type of the resource. Must be an object.} |
153+
| | | | |
154+
155+
#### Request body
156+
157+
{This section is optional.}
158+
159+
| Field | Type | Required? | Description |
160+
| ------ | ------ | --------- | ------------------------------- |
161+
| {id} | string | Required | {Unique identifier of the user} |
162+
| {name} | string | Optional | {Name of the user} |
163+
164+
### Request example
165+
166+
```text
167+
{Provide an example of the API request, filled with sample values.}
168+
```
169+
170+
### Response schema
171+
172+
| Status code | Schema | Description |
173+
| ----------- | --------------------------------------- | ---------------------------------------------------------------------------- |
174+
| `2xx` | [{ExampleDataType}](#data-model) | {Describe the result where the request succeeds.} |
175+
| `4xx` | [{ExampleErrorType}](#exampleerrortype) | {Describe the result where the request fails with the specified error code.} |
176+
177+
### Response example
178+
179+
```text
180+
{Provide an example of the API response, filled with sample values.}
181+
```
182+
183+
---
184+
185+
> Explore other templates from [The Good Docs Project](https://thegooddocsproject.dev/). Use our [feedback form](https://thegooddocsproject.dev/feedback/?template=API%20reference) to give feedback on this template.

‎v3/templates/how-to-guide.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Title
2+
3+
> The following template is taken from [The Good Docs Project](https://thegooddocsproject.dev/)
4+
> Some adjustments/clarifications have been made in the context of the **SuperTokens** docs.
5+
6+
Let's first clear the different between a _how-to guide_ and a _tutorial_.
7+
A _how-to guide_ is a step-by-step guide that helps a user accomplish a specific task (how to migrate users, how to configure sub domain login).
8+
A _tutorial_ will get you from 0 to a fully functioning example (quickstart).
9+
The easiest example here is a quickstart.
10+
| To quote [The Good Docs Project](https://www.thegooddocsproject.dev/template/how-to):
11+
| How-tos are task-oriented, while tutorials are learning-oriented
12+
13+
## Overview
14+
15+
Explain the main purpose of the how-to guide:
16+
17+
- This guide explains how to ...
18+
19+
Additonally, you can add more context and details to the actual task that the user will be performing:
20+
21+
- why the task is needed
22+
- when will this task be performed
23+
- if the task is complex, and you split it into multiple pages (sub-tasks) you can explain this here
24+
25+
## Before you start
26+
27+
{This section is optional}
28+
29+
Before you {insert a brief description of the task}, ensure:
30+
31+
- Prerequisite 1
32+
- Prerequisite 2
33+
- Prerequisite 3
34+
35+
## {Task name }
36+
37+
{Optional: Provide a concise description of the purpose of this task. Only include this if the purpose is not clear from the task title.}
38+
39+
{You can use this format to describe your steps:}
40+
41+
1. {Write the step here. Use a verb to start (bare infinitive form)}
42+
{Think about all the states a user might encounter (errors, warnings) and explain how to deal with them/overcome them.}
43+
44+
{Optional: Explanatory text}
45+
46+
{Optional: Code sample or screenshot that helps your users complete this step.}
47+
48+
{Optional: The result of completing this step.}
49+
50+
2. {Write the step here. Use a verb to start.}
51+
52+
2.1. {Substep 1}
53+
54+
2.2. {Substep 2}
55+
56+
### {Sub-task}
57+
58+
...
59+
60+
{This section is optional. Include a sub-task only if the task is big and complex.}
61+
62+
## See also
63+
64+
{Include references and/or links to other related documentation such as other how-to guides, conceptual topics, troubleshooting information, and limitation details if any.
65+
66+
- Reference link
67+
- Concept link
68+
- Troubleshooting link}

‎v3/templates/tutorial.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Title
2+
3+
> The following template is taken from [The Good Docs Project](https://www.thegooddocsproject.dev/template/tutorial)
4+
> Some adjustments/clarifications have been made in the context of the **SuperTokens** docs.
5+
6+
## Overview
7+
8+
In this tutorial, you'll learn how to {insert brief description of the main tutorial task}. This tutorial is intended for {audience}. It assumes you have basic knowledge of:
9+
10+
- Concept 1
11+
- Concept 2
12+
- Concept 3...
13+
14+
By the end of this tutorial, you'll be able to:
15+
16+
- Learning objective 1
17+
- Learning objective 2
18+
- Learning objective 3
19+
20+
{Most of our tutorials will probably have one main objective so you don't need to use a list all the time.}
21+
22+
## Background
23+
24+
{This section is optional. Feel free to use some of the text below to help you get started.}
25+
{Use this section to give more context to the user about what they are about to implement. E.g. explain what OAuth is, how ThirdParty proivders work, etc}
26+
27+
## Before you start
28+
29+
{Use this section to tell users about any prerequisites needed before they start the tutorial, such as:
30+
31+
- Expected prior knowledge.
32+
- Environments to set up and configure.
33+
- Packages to install.
34+
}
35+
36+
Before you start the tutorial, you should:
37+
38+
- Prerequisite 1
39+
- Prerequisite 2
40+
- Prerequisite 3...
41+
42+
## {Task name}
43+
44+
To get started, {the first thing your user should do}.
45+
46+
1. {Write the step here. Use a verb to start.}
47+
48+
{Explanatory text}
49+
50+
{Optional: Code sample or screenshot that helps your users complete this step}
51+
52+
{Optional: Result}
53+
54+
2. {Write the step here. Use a verb to start.}
55+
56+
a. {Substep 1}
57+
58+
b. {Substep 1}
59+
60+
## Summary
61+
62+
{Optional}
63+
{Use this section to summarize what the user learned in the tutorial.}
64+
65+
In this tutorial, you learned how to:
66+
67+
- Summary point 1
68+
- Summary point 2
69+
- Summary point 3..
70+
71+
## Next steps
72+
73+
{Use this section to share links to related tutorials, videos, or other documentation}.
74+
75+
Consider completing some other common tasks using {feature}:
76+
77+
- Task 1
78+
- Task 2
79+
- Task 3...

0 commit comments

Comments
 (0)