Improve technical writing style for docs

[methodofaction]

This PR is to discuss some stylistic choices and is not meant to be merged yet. With this PR I'm proposing the following stylistic changes to the docs:

1. Use sentence case in bulleted or numbered lists.
2. Always use "Click" instead of "Tap" or the more generic select.
3. Perhaps the most controversial opinion is to markdown as inline code when referring to text within UI elements (e.g. click on the Create Workflow button). The alternative would be to always bold it. I think inline code is neater and keeps bold for emphasis but I don't have a strong opinion about it.

Before:

After:

The following are conversations with ChatGPT to support these decisions:

In user interface instructions, should we use "click" or "tap", or something more generic such as "select"?

It depends on your audience and the devices they are using. Here's a breakdown to help decide:

1. If the Audience is Device-Specific:

• Desktop/Mouse Users: Use "click" because it's precise and commonly understood for mouse interactions.
• Touchscreen Users: Use "tap" as it's the most natural term for touchscreen devices.

2. If the Audience is Cross-Platform:

• Use "select" for a generic, device-agnostic term. It works across devices, whether users are clicking, tapping, or using keyboard navigation.
• You can also include context-specific guidance. For example:
  • "Select the option (click or tap depending on your device)."

3. Specific Considerations:

• If your interface adapts dynamically (e.g., progressive web apps or responsive sites), tailor the language based on the platform the user is on.
• For accessibility and inclusivity, use terms that are intuitive for assistive technology users. "Select" is often a safe and universally recognized choice in this case.

4. Style Guide Consistency:

• Stick to the same term throughout the instructions. For cross-platform apps or services, many companies default to "select" for simplicity.

Recommendation: If you're targeting multiple platforms and want to keep it simple and clear, go with "select". For device-specific content, "click" and "tap" are more intuitive.

Should we use sentence case in bulleted lists? what do major styleguides say about this?

Yes, using sentence case in bulleted lists is a common and widely accepted practice, but whether or not you use sentence case depends on the context and the style guide you're adhering to. Here's what major style guides say about this:

---

1. Sentence Case in Bulleted Lists

• Sentence case capitalizes only the first letter of the first word in each item, unless proper nouns or acronyms are used.
• It’s clear, reader-friendly, and preferred in most formal and professional contexts.

---

2. What Major Style Guides Recommend

APA Style (American Psychological Association)

• Recommends sentence case for bulleted and numbered lists.
• Each bullet point starts with a lowercase letter unless it’s a full sentence or contains a proper noun.
• Example:
  • Capitalize only the first word.
  • Use sentence case for clarity.

Chicago Manual of Style

• Favors sentence case for list items that are not full sentences.
• If the list items are complete sentences, each one should begin with a capital letter and end with appropriate punctuation.
• Example:
  • Write items as fragments, with no punctuation.
  • Use full sentences sparingly in bulleted lists.

AP Style (Associated Press)

• Similar to Chicago, sentence case is used unless the items are full sentences.
• Avoid ending sentence fragments with periods.

Microsoft Style Guide

• Recommends sentence case for list items that are not complete sentences.
• Use periods only for full sentences or when clarity requires them.
• Example:
  • Open the app.
  • Select the file.
  • Save your changes.

MLA Style (Modern Language Association)

• Generally uses sentence case for bulleted or numbered lists unless there is a stylistic reason to capitalize each word.

---

3. When to Use Title Case

• Some contexts (e.g., marketing or design-heavy documents) may use title case for emphasis or stylistic consistency.
• Example:
  • Open the App
  • Select the File
  • Save Your Changes

---

4. General Recommendation

• Sentence Case: Best for most professional, academic, and technical documents.
• Title Case: Reserved for creative or design-driven contexts.

Ultimately, consistency within your document or project is key. Choose the approach that aligns with your content's tone and purpose.

is there any case where lowercase bulleted lists are recommended?

Lowercase in bulleted lists is uncommon but can be recommended in specific cases, particularly for stylistic reasons or in certain informal, minimalist, or design-focused contexts. Here are examples and scenarios where lowercase might be appropriate:

---

1. Minimalist or Modern Design Styles

• Usage: Lowercase bulleted lists are sometimes used in websites, apps, or other design-heavy media to maintain a clean, casual, or sleek aesthetic.
• Example:
  • open the app
  • select your file
  • save your changes

---

2. Brand or Style Guidelines

• Some brands adopt lowercase text as part of their identity (e.g., apple’s use of lowercase in marketing materials). Bulleted lists may follow this pattern to maintain consistency.
• Example: If a brand consistently uses lowercase in headings and titles, it might carry that style into bulleted lists.

---

3. Creative or Casual Writing

• Informal blogs, creative writing, or non-academic content might use lowercase lists to create a conversational tone.
• Example:
  • brainstorm ideas
  • draft your post
  • share with friends

---

4. Linguistic or Typographic Experimentation

• Certain modern typographic trends or artistic works might intentionally use all-lowercase text, including in lists, for a distinct visual effect or to challenge traditional norms.
• Example: Poetry collections or art installations.

---

Considerations Before Using Lowercase

• Clarity: Lowercase might feel jarring or unpolished in formal or technical contexts.
• Consistency: If lowercase is used in one part of the document, it should apply consistently to similar content (e.g., headings, paragraphs).
• Audience: Ensure it aligns with the expectations of your audience and the tone of your material.

---

When Lowercase Lists Might Be a Bad Idea

• In professional, academic, or technical contexts where sentence case or title case is expected.
• For lists involving proper nouns or acronyms, as lowercase may cause confusion.

While lowercase bulleted lists can work in specific scenarios, they are best suited for informal, creative, or stylistically unique contexts. For most professional and technical settings, sentence case is still the go-to standard.

In technical documentation, how may I best represent user interface elements that I'm writing about, for example "click on the buy now button"

In technical documentation, user interface (UI) elements should be represented in a way that makes them visually distinct, easy to identify, and consistent throughout the documentation. Here's how you can best represent them:

---

1. Use Formatting to Differentiate UI Elements

• Bold Text: Highlight UI elements such as buttons, links, menu items, and tabs in bold.
  • Example: Click on the Buy Now button.
• Code Style/Monospace: Use code formatting (e.g., Buy Now) for elements like field names, command inputs, or system messages.
  • Example: Enter the value in the Price field.

---

2. Maintain Consistency

• Choose a single formatting convention (e.g., bold or monospace) and stick to it throughout your documentation.
• Ensure UI elements are consistently capitalized as they appear in the interface.

---

3. Use Contextual Clarity

• Describe the UI element with its full name or context if there might be ambiguity.
  • Example: Click on Buy Now in the top navigation bar.

---

4. Include Visual Aids

• Screenshots or diagrams can complement the written instructions and provide clarity, especially when the UI is complex.
  • Annotate screenshots to point out the Buy Now button.

---

5. Match the Style Guide

• If following a specific style guide, adhere to its recommendations. Here's what some major style guides suggest:
  • Microsoft Style Guide: Use bold for buttons and menu names (e.g., Buy Now).
  • Google Developer Documentation Style Guide: Use bold for buttons and menu names, and monospace for code elements.
  • Apple Style Guide: Use the exact capitalization and terminology as it appears in the interface.

---

6. Example Guidelines

• Buttons: Use bold text for button names.
  • Click the Submit button to save changes.
• Menu Items: Separate paths with angle brackets ( > ).
  • Go to File > Save As to save your document.
• Field Names: Use bold or monospace.
  • Enter your email in the Email Address field.
• Links: Use inline text formatting for hyperlinks.
  • Click Learn More to read about this feature.

---

7. Style for Accessibility and Localization

• Use phrases that are universally understood, avoiding jargon or overly specific terms.
• Avoid abbreviations that might be unclear in other languages if your documentation will be localized.

By using these practices, your documentation will be clear, professional, and user-friendly.

[juanmoliner]

Love it, thanks! We also had a writing guide for our blog that could be merged into this one:
https://docs.google.com/document/d/1qqD0l9e1J4OHqwSUWzazBA1m_SJ5wOpCr-MdikU7B1c/edit?usp=sharing