-
Notifications
You must be signed in to change notification settings - Fork 8
Home
Currently, the site is split into 5 major sections.
| Title | Use Case |
|---|---|
| Get Started | Full end-to-end, step-by-step instructions on local Docker deployment. |
| Deployment | Documents detailing interfaces of 3rd party reference implementations (Database, Secret Store, API Gateway, etc). |
| Tutorials | Full end-to-end, step-by-step instructions on a specific Feature or deployment flow. |
| Reference | Extended definitions, additional or miscellaneous info. Contains partial examples, but not full step-by-step instructions. |
| APIs | Swagger.io documented API endpoints. Managed via SwaggerHub. |
Tutorials contains fully guided (step-by-step) instructions that take the user from start (defining prerequisites) to finish (user has successfully setup/used/etc feature or deployment).
References is a location for general information not structured as a contiguous flow. Some small page sections may reference example code or commands, but do not contain full user instructions.
To create a new Tutorial, the top of the page should have a small paragraph description of high level feature details. Things to describe:
- What The Feature Is
- How It Works
- Why Do I Care
Most tutorials should comprise of at least 3 required header sections after the opening paragraph:
- What You'll Need
- What You'll Do
- Topic Section
- Next Steps (Not Required)
We typically use 6 of the total available admontions.
Example markdown of admonition:
!!! important "Important - Summary"
Details, links, and screenshots and any other required user information
| Admonition | Color | Use Case |
|---|---|---|
| Note | Blue | Notes are for general information or pointers to areas to find additional info or similar related documents. |
| Important | Soft Green | Important is more eye catching. Use for high use case notes. |
| Example | Purple | Example is for wrapping all example inputs or screenshots (excluding Success or Danger screenshots) |
| Success | Strong Green | Success is for wrapping successful outputs that demonstrate the expected output |
| Warning | Yellow | Warning is for potential security considerations or known use error areas. Use to guide users either towards solutions or very important recommendations. |
| Danger | Red | Danger is for critical areas. User errors during these steps could cause an unrecoverable failure. |