Appcircle Documentation Writing Checklist¶
Info
Appcircle has an official workflow documentation guideline. For step documentation requirements, see: https://docs.appcircle.io/workflows/how-to-create-a-new-workflow-step#4-documentation
This checklist defines the documentation quality standard for Appcircle. It is designed for contributors writing documentation for a mixed audience: technical users and non-technical or first-time CI/CD users.
The checklist prioritizes:
- Clarity and approachability
- Technical accuracy
- SEO and discoverability
- Consistency across all documentation pages
- A clear, direct tone
Each section explains what to do, why it matters, and provides examples.
1. Use Correct and Approved Brand & Product Names¶
What to do Always use official, approved capitalization and spelling for brands, products, platforms, and technologies.
Why it matters Incorrect naming reduces trust and confuses readers who may search for these terms.
Examples ✅ GitLab, Bitbucket, Azure DevOps, macOS, iOS, Xcode ❌ gitlab, bitBucket, azure devops, MacOS, IOS, xCode
2. Maintain Terminology & Format Consistency¶
What to do Use the same terminology, abbreviations, and formats consistently across the entire documentation. Follow existing conventions.
Why it matters Inconsistent terms make documentation harder to understand and maintain.
Examples
- Use Appcircle server (not Appcircle Server)
- Use Appcircle dashboard (not web UI)
- Use authentication (not auth)
- If the documentation uses
x86_64, do not introducex86-64
3. Use Direct, Action-Oriented Instructions¶
What to do Write step-by-step instructions in the imperative mood. Address the reader as "you" in explanatory or contextual text, but use plain commands when describing actions. Keep the tone neutral and confident — avoid harsh, blaming, or condescending phrasing.
Why it matters Imperative instructions are shorter, easier to scan, and unambiguous. They align with the conventions used by major technical documentation style guides (Google, Microsoft, Apple), which makes Appcircle docs feel consistent with the wider ecosystem readers already navigate.
Examples
✅ Select Build to start a new build.
✅ Run ./install.sh from the appcircle-server directory.
❌ You can start a build by selecting the Build button if you want to.
❌ Just hit Build — it's easy.
Condescending words such as just, simply, or easily are covered separately in rule #7.
4. Write for Non-Experts First¶
What to do Assume limited CI/CD and mobile platform knowledge. Explain concepts briefly when first introduced.
Why it matters Many readers are QA engineers, managers, or developers new to mobile CI/CD.
Examples ❌ Configure the iOS signing assets. ✅ Configure iOS signing assets, such as certificates and provisioning profiles, which are required before distribution.
5. Explain Both How and Why¶
What to do Whenever possible, explain why a step exists, not just how to perform it.
Why it matters Understanding intent builds confidence and reduces support requests.
Examples ✅ Select Xcode 15 to ensure compatibility with the latest iOS SDK.
6. Keep Paragraphs Short and Focused¶
What to do Use short paragraphs. Each paragraph should cover a single idea.
Why it matters Short paragraphs improve readability and scanning.
Formatting Rule
- Remove trailing (ending) whitespace from all lines.
7. Avoid Ambiguous or Dismissive Language¶
What to do Avoid words such as just, simply, or easily. Keep wording precise and neutral.
Why it matters These words can feel dismissive to users who struggle with a step.
8. Keep Code Examples Generic and User-Agnostic¶
What to do Avoid personal names, usernames, or environment-specific paths.
Why it matters Generic examples are reusable and easier to understand.
9. Specify Code Block Language Hints¶
What to do Always specify a language tag on fenced code blocks. Untagged blocks lose syntax highlighting and degrade the copy-paste UX.
Why it matters Readers rely on highlighting to parse commands, configuration, and code quickly. Tagged blocks also improve searchability and accessibility.
Examples ✅
./install.sh
✅
title: Build profile
description: ...
❌
./install.sh
Common tags: bash, yaml, json, swift, kotlin, xml, toml, text (for plain output).
10. Use Consistent Example Naming Conventions¶
What to do
Use the canonical sample project name spacetech (and its derivatives like spacetech-ios, com.example.spacetech) across all examples. Do not invent new project names per page.
Why it matters Consistency improves comprehension and cross-page compatibility. Readers learn the placeholder once and recognize it everywhere.
Examples
✅ spacetech, spacetech-android, com.example.spacetech
❌ myapp, demoproject, acme-mobile, developer-specific names
11. Prevent Duplicate Content (SEO Awareness)¶
What to do Avoid repeating the same explanations across pages. Reference existing sections instead.
Why it matters Duplicate content negatively impacts SEO and maintainability.
12. Always Include a Proper Document Header (Front Matter)¶
What to do Each page must start with a Docusaurus front matter block.
Why it matters Front matter powers SEO, navigation, and categorization.
Example
---
title: Unique document title
description: SEO-friendly description under 160 characters.
tags: [relevant, tags]
---
13. Use Proper Heading Hierarchy¶
What to do
Use one # (H1) per page — Docusaurus generates it from the front matter title, so start in-body content at ##. Do not skip heading levels (no ## directly followed by ####).
Why it matters A clean heading tree powers the page sidebar, anchor links, and screen-reader navigation. Skipped levels break accessibility and the table of contents.
Examples
✅ ## Overview → ### Prerequisites → ### Steps
❌ ## Overview → #### Prerequisites
14. Apply a Structured Tag Strategy¶
What to do
Use at least 2 lowercase tags per page. Reuse existing entries in tags.yml before defining new ones.
Why it matters Tags improve navigation, filtering, and discoverability. Pages with too few tags become orphaned in tag-based listings.
15. Use Absolute Paths for Internal Links¶
What to do Use absolute documentation paths starting from the documentation root. Do not include implementation-specific segments.
Why it matters Absolute paths are resilient to refactoring and align with Docusaurus routing.
Rules
- Do not include
/docsin internal links. - Do not include
.mdfile extensions.
Examples ✅ Correct:
'/build/build-process-management/build-profile-branch-operations'
❌ Incorrect:
'/docs/build/build-process-management/build-profile-branch-operations.md'
16. Use Descriptive Link Text¶
What to do Write link text that makes sense out of context. Avoid generic phrases like "click here", "this page", or bare URLs in prose.
Why it matters Descriptive link text improves accessibility (screen readers announce links out of context), SEO, and scannability.
Examples ✅ See the build profile configuration guide. ❌ For details, click here. ❌ See https://docs.appcircle.io/build/build-process-management/build-profile-branch-operations for more.
17. Ensure Page Discoverability¶
What to do
Every new page must be linked from at least one of: its parent index.md, a related feature page, or the FAQ. A page that is only reachable via direct URL is not discoverable.
Why it matters Pages that exist only via direct link rarely get read and never rank well. Discoverability is part of "done" for documentation.
18. Follow Screenshot & Visual Standards¶
What to do Ensure screenshots follow branding, size, and accessibility rules.
Why it matters Consistent visuals improve trust, clarity, and accessibility.
Key Rules
- 1440x900 resolution
- Light Theme
- Organization Name: Appcircle Team
- No personal names within visible profile, organization names or emails
- Pointer color:
#f69c21 - Always include alt text
- Visible applications icons should be related to Appcircle
- Full size (no cropping)
- Portal URLs should not be in Dev/Prep env. format (pref. dummy URL)
19. Add Version Constraints and Compatibility Notes¶
What to do Clearly state version requirements and compatibility boundaries using the appropriate admonition:
!!! info— minimum supported version, default behavior notes!!! warning— breaking changes, unsupported configurations, deprecations!!! danger— actions that risk data loss or downtime
Why it matters A consistent admonition vocabulary helps readers calibrate how seriously to take each note at a glance.
20. Include FAQ and Support Sections Where Applicable¶
What to do Add FAQ entries for common issues and a Need Help section at the end of the page.
Why it matters Helps users resolve issues quickly and reduces support load.
21. Ensure Cross-Page Consistency¶
What to do When updating a page, review and update related pages as needed.
Why it matters Inconsistent documentation creates confusion and mistrust.
22. Maintain Index Pages¶
When to create
Every directory with multiple subpages needs an index.md. Missing index files break breadcrumbs, navigation, and SEO.
When to update
When you add a new subtopic to an existing category, update the parent index.md so the new page appears in the navigation listing with a short description.
Why it matters
index.md pages are the entry points for each section. Out-of-date index pages hide new content from readers who navigate from the top down.
23. Add Redirections for Updated URLs¶
What to do
When updating a page URL, make sure to add a redirect in the netlify.toml.
Example
[[redirects]]
from = "/workflows/how-to-create-a-new-workflow-step"
to = "/workflows/how-to-create-an-integration"
status = 301
Why it matters Missing redirects for old URLs can cause broken help links within Appcircle and may also negatively impact SEO.
Final Note¶
This checklist represents the single source of truth for Appcircle documentation quality. All documentation PRs should be reviewed against these rules to ensure clarity, consistency, SEO compliance, and a positive reader experience.