Substantial changes (30+ minutes)

Major documentation projects that significantly expand or improve the Doc Detective documentation.

What counts as substantial

Documenting new features or major changes
Writing complete tutorials from scratch
Major restructuring of existing documentation
Creating comprehensive reference documentation
Large-scale content updates (multiple pages)
Adding new documentation categories

Before you start

For substantial contributions, it’s important to align with maintainers before investing significant time:

Check for existing issues: Look for documentation issues or feature requests.
Open a discussion: If no issue exists, open one describing your plans.
Get feedback: Wait for maintainer input before starting major work. If you don’t hear back in a few days, politely ping in the issue or on Discord.
Claim the work: Comment on the issue to let others know you’re working on it.

This prevents duplicate effort and ensures your contribution aligns with project goals.

Required: Local development environment

Substantial contributions require a local development environment to efficiently work across multiple files and see real-time previews.

👉 See Local development for detailed instructions.

Plan your contribution

Understand the user journey

Before writing, consider

Who is the target audience?
What are they trying to accomplish?
Why would they read this documentation?
When in their journey will they need this?

Choose the right content type

Use templates to structure your content:

Tutorial

Tutorials guide users through learning a concept end-to-end. You should use them when users need to understand a complete workflow or feature.

👉 Tutorial template

How-to guide

How-to guides help users accomplish a specific task. They’re generalized instructions for common tasks. They’re great when users know what they want to do but need instructions.

👉 How-to template

Reference

References provide technical specifications and details and are useful when users need to look up specific information.

👉 Reference template

Feature documentation

Feature docs are conceptual overviews about what a feature can do and why/when you’d want to use it. They’re educational and should be created or updated when a feature is new or has changed significantly.

👉 Feature template

Writing substantial documentation

Start with an outline

Get feedback on structure before writing full content:

Create a draft with section headings and bullet points
Commit and push to your branch
Open a draft pull request marked “WIP” or “Draft”
Request feedback on structure

This prevents rewrites later.

Write incrementally

Don’t try to write everything at once:

Write one section: Complete a single logical section
Commit and push: Save your progress
Review locally: Read it fresh after a break
Move to next section: Repeat the process

Commit often with clear messages:

Add overview section to feature X documentation
Document basic example for Y tutorial
Add troubleshooting section for Z

Include comprehensive examples

Substantial documentation needs examples users can learn from:

Basic example

Show the simplest use case:

basic-test.spec.json

{
  "tests": [
    {
      "steps": [
        {
          "goTo": "https://doc-detective.com"
        }
      ]
    }
  ]
}

Advanced example

Show real-world usage with more complexity:

advanced-test.spec.json

{
  "tests": [
    {
      "testId": "login-flow",
      "description": "Verify user can log in and access dashboard",
      "steps": [
        {
          "goTo": "https://example.com/login"
        },
        {
          "find": "#username"
        },
        {
          "type": {
            "keys": ["$USERNAME"]
          }
        },
        {
          "type": {
            "selector": "#password",
            "keys": ["$PASSWORD"]
          }
        },
        {
          "click": "button[type='submit']"
        },
        {
          "find": {
            "selector": ".dashboard",
            "matchText": "Welcome"
          }
        }
      ]
    }
  ]
}

Add visual aids

Consider adding

Diagrams: Use Mermaid for flowcharts and diagrams
Screenshots: Show key UI elements or results
Videos: For complex workflows (link to hosted videos)

Example Mermaid diagram:

Markdown

Rendered

```mermaid
graph TD;
    A[Write docs] --> B[Add tests];
    B --> C[Run tests];
    C --> D{Tests pass?};
    D -->|Yes| E[Deploy];
    D -->|No| A;
```

Testing your documentation

Build locally

Ensure the site builds without errors:

npm run build

Fix any build errors before submitting.

Test your examples

Every code example should be tested:

Run the code: Verify examples work as shown
Test variations: Ensure options are documented correctly
Check edge cases: Document limitations if found

Review process for substantial contributions

Initial review

Expect more detailed feedback on substantial contributions:

Technical accuracy: Is the information correct?
Content organization: Is the structure logical?
Completeness: Are there gaps that need filling?
Examples: Are they clear and correct?
Writing quality: Is it clear and concise?

Iterative improvement

Don’t expect to get it perfect on the first try:

Address feedback: Make requested changes.
Ask questions: If feedback is unclear, ask for clarification.
Suggest alternatives: If you disagree, explain your reasoning.
Iterate: Multiple review rounds are normal.

Technical writer involvement

For substantial contributions, a technical writer may:

Provide structural feedback
Suggest alternative approaches
Help with clarity and consistency
Polish language and formatting

This is collaborative. Your subject matter expertise plus writing expertise produces the best documentation.

After your contribution is merged

Celebrate. 🎉 You’ve made a significant contribution to Doc Detective. Thank you.

Help others discover your contribution:

Share on social media. Doc Detective is active on LinkedIn and will happily reshare contribution announcements.
Mention it in the Discord server.
Add it to your portfolio.

Need help?

Substantial contributions benefit from collaboration:

Planning phase: Discuss your approach in the issue or Discord.
During writing: Ask questions in draft pull requests.
During review: Don’t hesitate to ask for clarification.
Stuck?: Reach out in Discord. Maintainers are happy to help.

Recognition

Substantial contributions are highlighted:

Release notes mention significant documentation improvements
Contributors page lists all contributors
Social media shoutouts for major contributions

Thank you for investing your time in improving Doc Detective documentation.