agaric/documentation
10
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve formatting

Browse source
This commit is contained in:
benjamin melançon 2020-07-09 09:10:24 -04:00
parent 0f9c74b541
commit b3778a0227
1 changed files with 109 additions and 44 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

153
content-style-guide.md
View file

@ -19,7 +19,7 @@ Agaric’s voice is:
* Confident but not arrogant
* Cheerful but not Pollyanna-ish
* Unconstrained but not incomprehensible
* Open, curious, eclectic, but not scattered
* Open, curious, eclectic; but not scattered
### Writing about people
@ -500,7 +500,7 @@ Social media
What: Posts on Twitter, Facebook, Instagram, and LinkedIn that highlight blog posts, events, notable Agaric clients, and more
Length: 20-30 words
Owner: Marketing, support
Example: The City of Camrbidge used Agaric's FindIt platform to make it easier for people to find activities, events, and resources. Here's how: https://agaric.coop/work/find-it-cambridge
Example: The City of Camrbidge uses Agaric's Find It platform to make it easier for people to find activities, events, and resources. Here's how: https://agaric.coop/work/find-it-cambridge
See also: Writing for social media
#### Success message
@ -517,13 +517,13 @@ Length: 400-800 words
Example: Flat Comments in Drupal 8 without Dangerous Secret Threading
See also: Writing blog posts
#### Email Newsletter
#### Email newsletter
What: Email campaigns that market our services/products and inform or empower our users
Length: 200-1000 words
Example: We need one!
See also: Writing email newsletters
#### How To Article
#### How To article
What: Easily digestible content that walks users through a process or problem
Length: 300-1,000 words
Owner: Knowledge Base
@ -581,28 +581,38 @@ Include the most relevant keywords in your headings and subheadings, and make su
Use title case, unless the heading is a punctuated sentence. If the heading is a punctuated sentence, use sentence case. Use sentence case for subheadings regardless of end punctuation.
#### Links
Provide a link whenever you’re referring to something on an external website. Use links to point users to relevant content and trusted external resources.
Don’t include preceding articles (a, an, the, our) when you link text. For example:
Yes: Read the automation guide for details.
No: Read the automation guide for details.
Yes: Read the [content style guide](content-style-guide#links) for details.
No: Read [the content style guide](content-style-guide#links) for details.
If a link comes at the end of a sentence or before a comma, don’t link the punctuation mark.
Don’t say things like “Click here!” or “Click for more information” or “Read this.” Write the sentence as you normally would, and link relevant keywords.
If a link comes at the end of a sentence or before a comma, don’t link the punctuation mark.
Don’t say things like “Click here!” or “Click for more information” or “Read this.” Write the sentence as you normally would, and link relevant keywords.
Links should look different than regular copy, strong text, or emphasis text. They should have a hover state that communicates they’re interactive, and should have a distinct active and visited state. When setting the hover state of links, be sure to include focus state as well, to help readers using assistive technologies and touch devices.
#### Lists
Use lists to present steps, groups, or sets of information. Give context for the list with a brief introduction. Number lists when the order is important, like when you’re describing steps of a process. Don’t use numbers when the list’s order doesn’t matter.

If one of the list items is a complete sentence, use proper punctuation and capitalization on all of the items. If list items are not complete sentences, don’t use punctuation, but do capitalize the first word of each item.
#### Navigation
Use title case for main or global navigation. Use sentence case for subnavigation.
Navigation links should be clear and concise.
Radio Buttons
#### Radio Buttons
Use title case for headings and sentence case for button fields.
#### Related articles
Sometimes a long piece of copy lends itself to a list of related links at the end. Don’t go overboard—4 is usually plenty.
Related articles should appear in a logical order, following the step down/step up rule: The first article should be a step down in complexity from the current article. The second one should be a step up in complexity to a more advanced article.
@ -610,6 +620,7 @@ Related articles should appear in a logical order, following the step down/step
If you can, avoid repeating links from the body text in related articles.
#### Titles
Titles organize pages and guide readers. A title appears at the beginning of a page or section and briefly describes the content that follows.
Titles are (you guessed it) in title case.
Don’t use punctuation in a title unless the title is a question.
@ -624,85 +635,122 @@ Give every image descriptive alt text.
## Writing Blog Posts
Agaric blog posts are written by people from all over the company, not just those with “writer” in their job titles. We love having experts from around the office blog about their work. The person most familiar with the subject is in the best position to convey it, and the writers on the marketing team can help with brainstorming and editing as needed.
### Basics
We update the main Agaric blog a couple times every month. We generally publish:
* Feature, release, and integration announcements
* Agaric case studies
* Tips and tricks for web developers
* Tips and tricks for web developers
We publish blog posts that explain the “why” behind the work we do at Agaric. We want to show people that we're an industry leader and we use our blog to tell the stories behind our work and services.
We publish blog posts that explain the “why” behind the work we do at Agaric. We want to show people that we're an industry leader and we use our blog to tell the stories behind our work and services.
### Guidelines
When writing for the blog, follow the style points outlined in the Voice and tone and Grammar and mechanics sections. Here are some more general pointers, too.
**Be casual, but smart**
#### Be casual, but smart
This isn’t a term paper, so there’s no need to be stuffy. Drop some knowledge while casually engaging your readers with conversational language.
**Be specific**
#### Be specific
If you're writing about data, put the numbers in context. If you're writing about an Agaric client, give the reader plenty of information about the organization’s purpose, workflow, technical needs and results.
**Get to the point**
#### Get to the point
Get to the important stuff right away, and don’t bury the kicker. Blog posts should be scannable and easy to digest. Break up your paragraphs into short chunks of three or four sentences, and use subheads. Our users are busy, and we should always keep that in mind.
**Link it up**
#### Link it up
Feel free to link away from Agaric if it helps you explain something.
**Make 'em LOL**
#### Make 'em laugh
Agaric is a fun company, and we want our blog to reflect this. Feel free to throw in a joke here and there, or link out to a funny GIF or YouTube video when appropriate. Just don't overdo it.
**Use tags and keywords**
#### Use tags and keywords
In Drupal, add keywords that apply to your article. Look through existing posts for common tags. If you’re not sure if a word should be a tag, it probably shouldn’t.
**Use pictures**
#### Use pictures
Include images in your blog posts when it makes sense. If you’re explaining how to do something, include screenshots to illustrate your point. Make sure to use alt text.
## Writing Case Studies
This was heavily lifted from Nick Sabato at draft.nu
The goal of a case study is to show a named real-world client that we have worked with, along with the economic impact we had on their business, with social proof from a member of the client’s team.
What to enforce upfront
This involves three bits that need to be contractually enforced before starting any engagement:
## Writing case studies
*This section is heavily influenced by Nick Disabato of [Draft](https://draft.nu).*
A case study shows potential clients a named real-world client we have worked with, along with the impact (economic or other) we had on their business or organization, with social proof from one or more members of the client’s team.
### What to enforce upfront
This involves three bits that need to be contractually enforced before starting any engagement:
* The client must be explicitly named.
* The impact must be measurable. We cite a specific number that indicates the impact of our work. No numeric ranges here: only specific, precise numbers.
* Social proof must be present. Get an awesome quotation about the impact of Agaric’s work from the client and publish the case study with their name in it.
* These must be contractually enforced before the engagement begins, because they are always points of contention later.
### Components of a Great Case Study
**The problem.** Delineate why they came in, as well as any unique aspects of their expensive problem.
**Our thinking.** How did we begin approaching the problem? What research did we conduct to address it? What worked and what didn’t? What did we try?
**The outcome.** What was the measurable impact of our work?
**A quotation.** What did the client say about our work?
**What happened next.** Did the engagement expand in any capacity? Did we do other things for them that weren’t part of the initial, agreed-upon scope?
**A call to action.** Case studies exist to generate additional leads for the consultancy, so end with a clear next step for the reader to take – one that probably begins with introducing the kind of work we can do for them, and encourages them to apply.
Example: Draft’s latest case study, for BOOM! by Cindy Joseph, is now live.
## Writing Initiatives
**The problem.** Explain or enumerate why a client came to Agaric, as well as any unique aspects of their problem. (The more expensive a problem is for a client, the more clearly we can show our impact.)
**Our thinking.** How did we begin approaching the problem? What research did we conduct to address it? What worked and what did not? What did we try?
**The outcome.** What was the measurable impact of our work?
**A quotation.** What did the client say about our work?
**What happened next.** Did the engagement expand in any capacity? Did we do other valuable things for them that were not part of the initial, agreed-upon scope?
**A call to action.** Case studies exist to generate additional leads for the consultancy, so end with a clear next step for the reader to take – one that probably begins with introducing the kind of work we can do for them, and encourages them to apply.
## Writing about initiatives
Initiatives are meant to inform our audiences of how our work extends out to the greater world. Clearly convey their purpose, impact and how people can get involved.
## Writing Events
## Writing about upcoming events
Start with the essentials: what, when, where, cost and then follow with more specific details such as information about the people presenting or links to further background information.
## Writing Profile Pages
## Writing profile pages
This is an opportunity for people’s individuality to come through. Make these personable, highlight people’s passions, expertise and interesting facts that connect them to the reader.
## Writing Technical Content
## Writing technical content
Someone reading technical content is usually looking to answer a specific question. That question might be broad or narrowly-focused, but either way our goal is to provide answers without distraction.
For each project, consider your audience’s background, goal, and current mood. Ask these questions:
* Is the reader a prospective user, a new user, or an experienced user?
* What is the goal of the reader? To complete a task? To research a topic?
* Is the reader in the middle of a task? Are they in a hurry? Could they be frustrated?
* Is the reader a prospective user, a new user, or an experienced user?
* What is the goal of the reader? To complete a task? To research a topic?
* Is the reader in the middle of a task? Are they in a hurry? Could they be frustrated?
We don’t want to overload a reader with unnecessary information, choices to make, or complex ideas or phrases, when we don’t have to. This is particularly critical when a user may be new and/or frustrated. When relevant, prime the reader with a brief outline of an article’s focus in an introductory paragraph or section, and stick to the topic at hand. Keep sentences, paragraphs, and procedural steps focused and concise.
### Drafting technical content
Before you begin writing a new article, reach out to a subject matter expert (like an engineer, tester, designer, researcher, or technical support advisor) to get as much information as possible. You may only use a small portion of what you learn, but it helps to have more information than you need to decide where to focus your article.
Consider how many articles are needed and what article types will best describe a new feature or tasks to the user.
Outline your article, then write a draft. Stay in touch with your subject matter expert and revise as needed for accuracy, consistency, and length.
When you’re happy with a draft, pass it to another technical writer for peer review. Then show it to a lead technical writer for additional review and revisions. For new content or highly complex content, send last draft to your subject matter expert for final approval.
### Writing technical content
When writing technical content, follow the style points outlined in the Voice and tone and Grammar and mechanics sections. Here are some more general pointers, too.
**Stay relevant to the title**
@ -722,6 +770,7 @@ You Start list or Notes field.
Screenshots and GIFs may not be necessary for every article or process, but can be helpful to orient new users. Crop screenshots tightly around the action to focus attention.
### Editing technical content
We edit technical content based on three goals:
* Digestibility
* Cut or tighten redundancies, gerunds, adverbs, and passive constructions.
@ -815,10 +864,11 @@ As you write, consider the following:
Many of the best practices for writing for accessibility echo those for writing technical content, with the added complexity of markup, syntax, and structure.
## Guidelines
* Avoid directional language
* Avoid directional instructions and any language that requires the reader to see the layout or design of the page. This is helpful for many reasons, including layout changes on mobile.
Yes: “Select from these options,” (with the steps listed after the title)
Yes: “Select from these options” (with the steps listed after the title)
No: “Select from the options in the right sidebar.”
### Use a skip navigation link
@ -901,45 +951,59 @@ Yes: Most Agarics use contractions, but Micky does not.
No: Most Agarics use contractions, but not Micky.
#### Repeat markers in a list or series
Yes: Use Agaric's FindIt platform to post opportunities, to list service providers, and to connect kids with activities.
No: Use Agaric's FindIt platform to post opportunities, list service providers, and connect kids with activities.
Yes: Use Agaric's Find It platform to post opportunities, to list service providers, and to connect kids with activities.
No: Use Agaric's Find It platform to post opportunities, list service providers, and connect kids with activities.
#### Leave in words like “then,” “a,” “the,” “to,” and “that," even if you think they could be cut
Yes: If there is not a test site set up, then you’ll need to create a test site before you can safely evaluate functionality changes.
No: If there is not a test site set up, you’ll need to create a test site before you can safely evaluate functionality changes.
Yes: When sending an email, it is necessary to have a “From:” name, a “From:” address, and a subject line.
No: When sending an email, it is necessary to have a “From:” name, “From:” address, and subject line.
Yes: Be sure that you are truly ready to show your work to the world before pushing your changes to live.
No: Be sure you are truly ready to show your work to the world before pushing your changes to live.
#### Avoid ambiguity and confusion
Many words, parts of speech, and grammar mechanics we don’t think twice about have the potential to cause confusion for translators and non-native English speakers. Here are some of the big trouble spots to avoid.
#### Avoid unclear pronoun references
Yes: Many believe that making functionality changes directly to a live site is OK. Such action can actually cause a site to break. Making functionality changes directly to a live site is not recommended.
No: Many believe that making functionality changes directly to a live site is OK. This can cause a site to break. It is not recommended.
#### Avoid -ing words
In English, many different types of words end in -ing: nouns, adjectives, progressive verbs, etc. But a translator who is a non-native English speaker may not be able to recognize the distinctions and may try to translate them all in the same way.
Because of this, we want to avoid -ing words when possible. One exception to this rule is words like “graphing calculator” and “riding lawnmower,” where the -ing word is part of a noun’s name and can’t be worked around.
Here are some other cases where you might see -ing words, and suggestions for how to edit around them.
#### Gerunds
##### Gerunds
Yes: In this article we will talk about training participant signups.
No: In this article we will talk about getting training participants.
#### Adjectives
##### Adjectives
Yes: At the top of the page, there is Ben with a smile on his face.
No: At the top of the page, there is a smiling Ben.
#### Parts of verbs
##### Parts of verbs
Yes: Several developers are currently working on that feature.
No: Several developers are working on that feature. (When you can’t easily avoid the -ing word, it may help to add an adverb to clarify the meaning.)
#### Parts of phrases modifying nouns
##### Parts of phrases modifying nouns
Yes: From our backyard, we could hear the planes that took off from the airport.
No: From our backyard, we could hear the planes taking off from the airport.
#### Other words and mechanics to avoid
* Slang, idioms, and cliches
* Contractions (English contractions may not be recognizable to all translators)
* Shortened words, even if they’re common in English (use “application,” not “app”)
@ -951,6 +1015,7 @@ No: From our backyard, we could hear the planes taking off from the airport.
* Synonyms, generally. Don't use a lot of different words for the same thing in a single piece of writing. Instead of mixing it up with “campaign,” “newsletter,” “bulletin,” etc., pick one term and stick with it.
#### Beware words with multiple meanings
“Once” (could mean “one time,” “after,” “in the past,” or “when”)
Yes: After you log in, you will see your account’s Dashboard.
No: Once you log in, you will see your account’s Dashboard.