Contribution Guide
This guide will help you modify and edit this website.
Introduction
This guide will help you modify and edit the HMCTS Operations Runbooks website. The files within the hmcts/ops-runbooks repository are processed by GitHub Actions to create a static website. These actions are triggered when a merge is completed into the main branch.
Our Operations Runbooks serve as the single source of truth for operational procedures, troubleshooting guides, and best practices. By contributing to this documentation, you help maintain and improve our Platform Operations knowledge base.
Benefits of Operations Runbooks Documentation
- Knowledge Transfer: Document your knowledge to enable task reassignment and team flexibility. Remember: If you don’t document it, you own it
- Continuous Improvement: The second person to use a runbook often improves it, leading to iterative enhancements.
- Single Source of Truth: Ensure all team members have access to the most up-to-date information.
- Onboarding Tool: New platform team members can review and update runbooks as part of their onboarding process.
- Collaborative Environment: Encourage feedback and improvements from all team members.
Getting Started
- Familiarise yourself with the existing documentation structure.
- Identify areas where you can contribute or improve existing content.
- Set up your development environment using GitPod (see Contributing section).
- Make your changes and submit a pull request for review.
Contributing (using GitPod)
HMCTS way used Gitpod, browser based IDE where ruby/ruby dependencies can be auto-installed from dependency file. Contributors can open the repo in Gitpod and easily make changes and recompile the static site without having to worry about managing their ruby version/dependencies on the local machine
To get started with GitPod:
- Open in Gitpod
- Make your desired changes to the documentation
- Preview your changes using the built-in server
- Commit and push your changes to create a pull request
Best Practices for Documentation
- Keep content clear, concise, and actionable
- Use headings and lists to improve readability
- Include examples and screen shots where appropriate
- Update version numbers and last_review dates when making changes
- Cross-reference related documents to improve navigation