evergreen-docs:dig_style_guide
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
evergreen-docs:dig_style_guide [2020/10/27 10:52] – [Common Mistakes] aneiman | evergreen-docs:dig_style_guide [2024/08/15 11:55] (current) – [Screenshots] aneiman | ||
---|---|---|---|
Line 9: | Line 9: | ||
==== Add a Table of Contents to the top of each AsciiDoc file ==== | ==== Add a Table of Contents to the top of each AsciiDoc file ==== | ||
- | This simply means adding this AsciiDoc line near the top of each '' | + | This simply means adding this AsciiDoc line near the top of each '' |
- | <code asciidoc>: | ||
- | ==== Use underline | + | <code asciidoc> |
+ | : | ||
+ | |||
+ | |||
+ | |||
+ | ==== Use prefix/ | ||
The basic reasons are: | The basic reasons are: | ||
Line 52: | Line 56: | ||
For historical purposes, the old xref syntax is below | For historical purposes, the old xref syntax is below | ||
- | **DO NOT USE THIS!** | + | The below is an example of the now-deprecated cross reference style. **DO NOT USE THIS!** |
<code asciidoc> | <code asciidoc> | ||
<< | << | ||
Line 63: | Line 67: | ||
===== General ===== | ===== General ===== | ||
* **Avoid changing section titles**. These are used to auto-generate anchor tags which are often used for links. Change with care, and check for links in other docs. | * **Avoid changing section titles**. These are used to auto-generate anchor tags which are often used for links. Change with care, and check for links in other docs. | ||
- | * Always **review changes** before committing to master | + | * Always **review changes** before committing to main (and check the updated web page the next day to make sure it worked right). |
- | * Always use **spell-check** on new content (including when porting old docs into master). | + | * Always use **spell-check** on new content (including when porting old docs into main). |
* AsciiDoc code lines should be 80 characters long or shorter. (Occasionally, | * AsciiDoc code lines should be 80 characters long or shorter. (Occasionally, | ||
* Screenshots should be smaller than 1050 pixels wide (when possible). | * Screenshots should be smaller than 1050 pixels wide (when possible). | ||
+ | * Rather than recreating documentation text in multiple adoc files, instead link directly to the main adoc for the feature. | ||
===== Formatting ===== | ===== Formatting ===== | ||
==== Headers ==== | ==== Headers ==== | ||
Line 103: | Line 108: | ||
* This allows AsciiDoc to auto-number the items as needed. | * This allows AsciiDoc to auto-number the items as needed. | ||
* **Ampersands** should be left as is (&). Don't use an HTML entity (which ironically causes errors in our HTML generator). | * **Ampersands** should be left as is (&). Don't use an HTML entity (which ironically causes errors in our HTML generator). | ||
+ | * If an ampersand appears in the staff client or OPAC use the ampersand in the documentation. | ||
* Any **code and command line commands** should be marked as +code+ or `code` | * Any **code and command line commands** should be marked as +code+ or `code` | ||
* If the code or command is hard to read when included in the paragraph, consider using a code block: | * If the code or command is hard to read when included in the paragraph, consider using a code block: | ||
Line 181: | Line 187: | ||
* **Don' | * **Don' | ||
* **When replacing a screenshot**, | * **When replacing a screenshot**, | ||
+ | * Image syntax: '' | ||
+ | * Starting with version 3.8 screenshots should be put into folders with the same name as the page the images appear on. For example, if your page is circulation_policies.adoc in the admin folder the image folder would be called circulation_policies and would be in admin -> assets -> images -> circulation_policies. | ||
+ | * Alt text: Please remember to include alt text in the image syntax for descriptive and accessibility reasons. | ||
+ | * Screen shots can be from any installation of Evergreen, as long as it does not contain any personal identifiable information, | ||
===== Common Mistakes ===== | ===== Common Mistakes ===== | ||
evergreen-docs/dig_style_guide.1603810370.txt.gz · Last modified: 2022/02/10 13:34 (external edit)