| name | write-documentation |
| description | Follow Adobe content writing standards when writing documentation for the Adobe Labs website. |
Documentation standards
Follow and understand Adobe content writing standards when writing documentation for the Adobe Labs website.
When this skill applies
- Writing or updating documentation for this codebase
- Writing any documentation that is shipped to external consumers
- Creating documentation that is internal
- Drafting Jira tickets
- Writing a pull request description
Example
🚨 Not following Adobe content standards
THE COLUMNS BLOCK figures out how many columns you have based on however many cells are in the first row and it adds a class like columns-2-cols or columns-3-cols or whatever number applies to the block wrapper, and ALSO if a column's only content is a single picture it gets tagged with columns-img-col so you can target it in CSS, and this matters because otherwise your image columns won't get the special layout treatment and things might look broken on smaller screens if you forget this!!!
✅ Following Adobe content standards
The columns block adds a columns-<n>-cols class to the block, where <n> is the number of cells in the first row. Any column whose only content is an image is also tagged columns-img-col, so image columns can be styled separately from text columns.
Key patterns
Most often, documentation is written in Markdown format.
Markdown syntax reference
Headers
# H1 Header
## H2 Header
### H3 Header
#### H4 Header
##### H5 Header
###### H6 Header
Text Formatting
**Bold text**
_Italic text_
**_Bold and italic_**
~~Strikethrough~~
`Inline code`
> Blockquote
> Multiple lines
> in blockquote
---
Horizontal rule (also \_\_\_ or \*\*\*)
Lists
Unordered list:
- Item 1
- Item 2
- Nested item 2.1
- Nested item 2.2
- Item 3
Ordered list:
1. First item
2. Second item
1. Nested item 2.1
2. Nested item 2.2
3. Third item
Task list (GitHub Flavored Markdown):
- [x] Completed task
- [ ] Incomplete task
- [ ] Another task
Links and Images
[Link text](https://example.com)
[Link with title](https://example.com 'Link title')
Reference-style link:
[Link text][reference]
[reference]: https://example.com
Automatic link:
<https://example.com>
<email@example.com>
Reference-style image:
![Alt text][image-ref]
[image-ref]: image.png
Code Blocks
Inline code: `const x = 5;`
Code block with language:
```javascript
function hello(name) {
console.log(`Hello, ${name}!`);
}
```
```bash
npm install
npm start
```
Tables
Simple table:
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1 | Data | Data |
| Row 2 | Data | Data |
Aligned columns:
| Left | Center | Right |
|:-----|:------:|------:|
| Left | Center | Right |
| Text | Text | Text |
Resources
