Writing documentation

In this document, we assume you have a basic understanding of what Adapt is and does. If you're completely new, we recommend you first check out the Framework in five minutes to learn the basics.

What skills do I need?

Good news! Contributing documentation to Adapt doesn't require technical coding skills. If you can write clearly and use basic formatting, you can help improve the project's documentation.

Required

Clear writing: The ability to explain concepts in plain English (or other languages for localization). Good documentation is concise, accurate, and easy to understand.

Basic Markdown: Most Adapt documentation uses Markdown for formatting. It's simple to learn - headings, lists, links, and code blocks cover 90% of what you'll need.

GitHub account: You'll need a free GitHub account to contribute documentation. For plugin documentation you'll submit pull requests; for wiki pages you may need maintainer access (see below).

Beneficial

The following aren't essential, but will help you contribute more effectively:

Git basics: Understanding how to fork repositories, create branches, and make pull requests makes it easier to contribute to plugin documentation. GitHub's help documentation is a good starting point.

Adapt experience: Having built a course or used the Authoring Tool helps you understand what users need to know. You'll write better documentation if you've experienced the pain points firsthand.

Screenshot tools: Many documentation improvements benefit from visual aids. Knowing how to capture and annotate screenshots makes your contributions more valuable.

Types of documentation

Adapt documentation exists in several places, each serving a different purpose:

Wiki pages

The Adapt Framework wiki contains guides, tutorials, and reference documentation. Topics include:

• Getting started guides for new users
• Developer guides for plugin creators
• Core concepts and architecture explanations
• Migration guides between framework versions

How to contribute: Wiki editing is restricted to project maintainers. If you'd like to contribute wiki content, create a GitHub issue with your proposed changes or draft content.

Plugin READMEs

Every plugin repository includes a README.md file that documents:

• What the plugin does
• Installation instructions
• Configuration options (linking to example.json)
• Accessibility considerations
• Browser/device compatibility
• Known issues

How to contribute: Plugin READMEs require pull requests (see Submitting your documentation below).

Example JSON files

Each plugin's example.json file shows sample configuration with inline comments. These are crucial for course authors learning to use the plugin.

How to contribute: Requires a pull request to the plugin repository.

Properties schema files

The properties.schema files document configuration options for the Authoring Tool. While more technical, improving descriptions and help text makes the AT easier to use.

How to contribute: Requires a pull request to the plugin repository.

Finding something to work on

Not sure where to start? Here are some ways to find documentation that needs help:

Browse the wiki for gaps

Look through the wiki sidebar and read pages that interest you. Common issues:

• Outdated information (references to old framework versions)
• Placeholder pages marked "TODO" or "Coming soon"
• Incomplete guides that trail off mid-explanation
• Missing screenshots or examples
• Broken links

Check plugin repositories

Visit the Adapt Plugin Browser and explore plugin repositories. Look for:

• READMEs that are sparse or unclear
• Missing or outdated screenshots
• Incomplete example.json files
• Configuration options without clear descriptions
• No accessibility guidance

Monitor GitHub issues and discussions

Browse GitHub issues across Adapt repositories to see what questions users are asking. If people keep opening issues about the same topics, the documentation probably needs improvement.

Review GitHub issues

Search for issues labeled documentation or good first issue across Adapt repositories. These often highlight specific documentation gaps that need filling.

Documentation standards

Good documentation follows consistent style and formatting. Here are the conventions used across Adapt:

Writing style

• Be concise: Get to the point quickly. Technical documentation isn't creative writing.
• Use active voice: "Click the button" not "The button should be clicked"
• Define acronyms: First use should be spelled out: "Learning Management System (LMS)"
• Use examples: Show, don't just tell. Code snippets and screenshots are invaluable.
• Test your instructions: If you're writing a how-to, follow the steps yourself to ensure they work.

Markdown formatting

• Use **bold** for UI elements: "Click the Save button"
• Use _italics_ for emphasis or introducing new terms
• Use `backticks` for code, file names, JSON properties, and commands
• Use code blocks with syntax highlighting for longer code examples:

```javascript
const example = "like this";
```

• Use numbered lists for sequential steps
• Use bullet lists for non-sequential items
• Include alt text for images: ![Description of image](image-url.png)

Linking

• Link to other wiki pages using relative links: [Page Title](Page-Title)
• Link to specific sections using anchors: [Section](#section-heading)
• Link to external resources with descriptive text: [Markdown guide](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
• Avoid "click here" links - use descriptive link text

Screenshots and images

• Use screenshots sparingly but effectively
• Crop images to show only relevant parts of the interface
• Annotate screenshots with arrows or highlights to draw attention to key areas
• Keep file sizes reasonable (compress large images)
• Use descriptive file names: mcq-configuration-example.png not screenshot1.png

Submitting your documentation

How you submit documentation changes depends on what you're editing:

Wiki pages

Wiki editing is restricted to project maintainers. To contribute wiki improvements:

1. Create an issue: Open a new issue in the framework repository
2. Include your content: Either write your proposed changes in the issue, or attach a Markdown file with your draft
3. Collaborate: Maintainers may provide feedback or request changes
4. Maintainer publishes: Once approved, a maintainer will publish your content to the wiki

Alternatively, if you become a regular contributor, you may be granted maintainer access to edit the wiki directly.

Plugin documentation (READMEs, example.json, properties.schema)

Plugin documentation lives in GitHub repositories and requires pull requests:

1. Fork the repository: Click the "Fork" button on the plugin's GitHub page
2. Make your changes: Edit the relevant files in your fork
3. Commit your changes: Write a clear commit message describing what you changed
4. Create a pull request: Submit your changes back to the main repository

If you're new to this process, GitHub's guide on proposing changes to a project walks through each step.

Before submitting

Before you submit changes, double-check:

• Is the information accurate? Don't guess - verify facts against the code or by testing.
• Have you checked spelling and grammar? Typos undermine credibility.
• Do links work? Click every link to ensure they go to the right place.
• Do code examples work? Test any JSON or code snippets you include.
• Have you followed the style guide? Consistent formatting makes documentation easier to scan.

Creating a good pull request (for plugin docs)

When submitting a PR for documentation changes:

• Reference related issues: If you're addressing a known documentation gap, link to the issue
• Explain what you changed: "Updated README to clarify _isEnabled behavior" is better than "Updated README"
• Note what you tested: "Verified configuration works with Framework v5.55" builds confidence
• Include screenshots: If you added/changed visuals, show before/after

Review process

Documentation pull requests typically get reviewed quickly since they don't require extensive code testing. A maintainer will:

• Check for accuracy
• Verify formatting looks correct
• Suggest improvements if needed
• Merge once approved

Don't be discouraged if you get feedback - it's normal and helps make the documentation even better!

Tips for effective documentation

From our experience, here's what makes documentation truly helpful:

Start with "why"

Before explaining "how," explain "why" someone would use a feature. Context helps users understand when to apply what they're learning.

Address common mistakes

If there's a configuration option users frequently get wrong, highlight it. "Note: this must be set to true for..." prevents frustration.

Include edge cases

Document not just the happy path but also: What happens if a property is omitted? What are valid values? What breaks if you configure it incorrectly?

Show real examples

Generic examples like "title": "Example Title" are less helpful than realistic ones: "title": "Fire Safety Quiz". Users pattern-match against examples.

Update when things change

If you notice outdated documentation while working on something else, fix it! Small updates add up.

Think about different audiences

A course author needs different information than a plugin developer. Consider who will read your documentation and what they need to know.

Get help

Stuck or unsure about something? Open a GitHub issue in the relevant repository to ask questions or discuss documentation improvements with the maintainers.

Finally...

If you've made it this far and contributed your first documentation improvement, congratulations!

Documentation is the unsung hero of open source projects. Every typo you fix, every screenshot you add, and every unclear explanation you clarify makes Adapt more accessible to new users. We greatly appreciate any time you can give to the project, however small you think it may be.