Getting Started with Documentation#
Welcome to the PSRule.Rules.Azure documentation contribution guide! This walkthrough will help you understand how to update and improve the documentation, including general documentation and rule-specific documentation. It serves as an extension of the existing Writing Documentation Guide.
Why Contribute to Documentation?#
Good documentation is essential for helping new users and contributors understand how to use PSRule.Rules.Azure effectively. By contributing, you make it easier for others to get started, understand rules, and use them correctly.
Prerequisites#
Before you start contributing, make sure you have:
- A GitHub account
- A fork of the repository
- Git installed on your system
- A basic understanding of Markdown
Locating Documentation Files#
The documentation is stored in the docs/
directory.
Some key areas you might like to improve include:
- Rule recommendations:
docs/en/rules/
- Scenarios and examples:
docs/customization/
anddocs/scenarios/
- PowerShell cmdlet and conceptual topics:
docs/commands/
anddocs/concepts/
- General contribution guidelines:
docs/license-contributing/contributing.md
- Writing documentation:
docs/license-contributing/writing-documentation.md
How to Update Documentation#
Follow these steps to make and submit updates:
-
Fork and clone the repository
-
Create a new branch for your changes
-
Find the relevant documentation file Navigate to
docs/license-contributing/
for general documentation,docs/rules/
for rule-specific documentation, or other locations mentioned above. -
Edit the file using Markdown
Use a text editor like VS Code or a Markdown editor to make changes. -
Update
mkdocs.yml
Ensure that the new documentation page is included in themkdocs.yml
navigation structure under:- Samples: samples.md - License and contributing: - Index: license-contributing/index.md - Get started contributing: license-contributing/first-contributors-guide.md - Writing documentation: license-contributing/writing-documentation.md - Getting started with documentation: license-contributing/getting-started-with-documentation.md - Past hackathons: license-contributing/hackathons.md - Related projects: related-projects.md
-
Preview changes locally If using MkDocs, run:
Openhttp://127.0.0.1:8000/
in your browser to preview. -
Commit and push your changes
-
Create a Pull Request (PR)
- Go to your fork on GitHub.
- Click "Compare & pull request".
- Provide a clear title and description.
- Submit the PR and wait for review.
Best Practices for Writing Documentation#
- Keep it simple – Use clear and concise language.
- Follow the existing structure – Stay consistent with current documentation.
- Use examples – Help users understand with practical examples.
- Check formatting – Ensure correct Markdown syntax.
- Preview before submitting – Avoid typos and formatting errors.
Troubleshooting Common Issues#
Issue | Solution |
---|---|
Formatting errors | Use a Markdown linter or preview the file before committing. |
Merge conflicts | Rebase with the latest main branch. |
PR feedback required | Make requested changes and push again. |
Conclusion#
Contributing to documentation is a great way to support the PSRule.Rules.Azure community. By improving documentation, you help new users onboard faster and enhance the project's usability. Thank you for contributing!