Hello! Thank you for choosing to help contribute to the SendGrid documentation site! There are many ways you can contribute and help is always welcome. When writing documentation, we ask you to consider the following style guidelines.
We strive to make our documentation concise, clear, organized, and scannable.
- Use conversational language and industry-standard terms when possible.
- Contractions are OK and preferred.
- Use bulleted lists and numbered steps where applicable.
- Use US English spelling.
When documenting a UI action, make it bold. Avoid using the word "button" in the step and simply refer to the name on the UI element. For example, "Enter your username and password, and then click login."
Where possible, write pages in a "jobs to be done" format. Jobs to be done style includes:
- Table of contents at the beginning
- "Additional Resources" section at the end
- Include sections to achieve the goal, with steps for each task (numbered steps, clear directions, and correct UI workflow) For an example, see Sending a campaign
Avoid passive voice. A good way to check if your sentence is in passive or not is to add "by zombies" to the end of it. If zombies end up doing the action, it's passive.
Example: Any templates, campaigns, contacts, or API keys created by the teammate will not be deleted....by zombies(!)
Use numerals instead of spelling them out. However, if a number leads off the sentence, spell it out. YES: “SendGrid offers 10 templates in Marketing Campaigns.” YES: “Ten templates are included in Marketing Campaigns.”
When referring to other pages in the documentation, make sure your link text is descriptive.
YES: For more information, see [Event Webhook] documentation. NO: For more information, click [here].
The new head matter looks like this with the new Knowledge Center:
---
layout: page
weight: 0
group:
title:
seo:
title:
description:
keywords:
navigation:
show: true
---
The sections in Bold are the categories. The "group" field in the head matter pertains to the different headers article residing under a specific category. The group designation is after the colon of the "group" field.
Sending Email
- Automation: automation
- Building Email: building-email
- Delivery & Optimization: delivery-optimization
- Building Email with Marketing Campaigns: marketing-campaigns
- Building Transactional Email: transactional-email
- Tracking: tracking
- Platform Partners: platform-partners
Managing Contacts
- Managing Contacts with Marketing Campaigns: managing-contacts
Analytics and Reporting
- Statistics: statistics
- Click Tracking: click-tracking
- Email Activity Feed: email-activity
- SendGrid Partners: partners
- Tracking: tracking
Account and Settings
- Account Management: account-management
- Inbound Parse: inbound-parse
- Sender Authentication: sender-authentication
- IP Management: ip-management
- Teammates & Subusers: teammates-subusers
- Troubleshooting: troubleshooting
- Security: security
- Billing: billing
Sending Email
- SendGrid v2 API: api-v2
- SendGrid v3 API: api-v3
- Frameworks: frameworks
- Mail Clients: mail-clients
- Mail Servers: mail-servers
- SendGrid Partners: partners
- SendGrid Plugins: plugins
- Send SMTP: smtp
- X-SMTPAPI Header: x-smtpapi
- Tracking: tracking
- Open Source Apps: open-source
Parsing Email
- Inbound Parse: inbound-parse
Tracking Events
- Code Examples: code-examples
- Getting Started: getting-started
- SendGrid Partners: partners
- Reference & Troubleshooting: reference-troubleshooting
Partners
- Migration: partner-migration
- Platform Partners: platform-partners
"Additional resources" is an h2 section that contains 3 to 5 bullet points with links out to other closely related pages. These pages could be SendGrid blogs or docs pages with information about next steps, use cases, or other things a user should consider when they are completing the task on the page. Every page should have an additional resources page, so if it doesn't, feel free to add one!
Here is an example "Additional resources" section: https://sendgrid.com/docs/ui/sending-email/editor/#additional-resources
Here is example formatting:
## Additional resources
* [Sending an email]({{root_url}}/ui/sending-email/how-to-send-email-with-marketing-campaigns/)
* [A/B testing]({{root_url}}/ui/sending-email/a-b-testing/)
* [Campaign statistics]({{root_url}}/ui/analytics-and-reporting/marketing-campaigns-stats/)
* [Marketing templates]({{root_url}}/ui/sending-email/working-with-marketing-templates/)
- SaaS - note capitalization
- Cloud-based - note hyphen
- Warmup - one word with no hyphen
- Mail stream - 2 words
- Statistics - do not shorten to “stats”
- Email - NOT e-mail
- Deactivate - not inactivate
- Recipients - The people that receive email from SendGrid Customers. Not “users” or “customers”.
- “Log in” - verb
- “login” - noun
- “sign up” - verb
- “sign-up” - noun
- “username” - one word
When referring to file types, like a PDF file, or a CSV file, refer to it as a CSV file, and not as a .csv file, unless it is an example file, like my-file.csv. When it's an example file, it should be in code syntax.
- Use Oxford commas.
- Refrain from using exclamation points when possible.
- Watch out for 2 spaces after periods--there can be only one.
- Keep periods and punctuation marks inside the quotation marks.
- When in doubt...make it lowercase!
- Use sentence case for headings unless it contains a feature name or UI element. (For example, Getting started with the Design Editor.)
- Only capitalize exclusive feature names like “Event Webhook” and “Marketing Campaigns” not, “drag & drop editor” or “transactional templates".
These are great for quick information that you want to highlight to a user. Especially for “gotchas” or “neat tricks”. Please use the tags below to show these in your content.
<call-out type="warning">
Your text here
</call-out>
<call-out type="beta">
Your text here
</call-out>
<call-out>
Your text here
</call-out>
Not every single page or step needs an accompanying screenshot. When in doubt, follow the guidelines below.
- The layout of the main elements and areas of the interface with captions. For example, the toolbar, status bar, main menu, pop-up menu. This avoids needing to explain in words: “On the bar on the left, click on the second button from the top”.
- Each action that significantly changes the state of the system, interface or data.
- Pop-up (modal) windows.
- Install and uninstall wizards (unless there is something really unusual about a lot of the settings).
- Login pages.
- Standard dialog windows (open, save).
- Endless drop-down lists (select language or country).
- Individual buttons (use text).
- Anything that is already described in detail or included on other screenshots – better to provide a link.
- Screens containing details about the version, rights, etc. If a new version comes out, you may need to change numbers or letters on every single screenshot.
- Pieces of code, configs, etc. Instead, insert these as formatted text – it looks better, and users can easily copy them.
Please use PNG, GIF, or JPG files. Give the screenshots unique, meaningful names, obeying a specific format, such as general_settings_privacy. Avoid spaces, uppercase letters, and excessively long names.
Images should be located in the following directory:
docs/static/img/
When possible, try to take screenshots at a size that is twice what it will need to be on the page.
As a best practice, all screenshots should have accompanying alt text.
Use the following format when inserting an image into the docs:
