Add documentation contribution and screenshot review requirements #46

Goal

Add the missing contribution guidance and pull request template for the LibreSign documentation repository so every documentation contribution is reviewed from the rendered result, not only from the source diff.

This repository is built with Sphinx. Reviewers need to see how changed pages actually render because headings, lists, tables, code blocks, images, cross-references and spacing can be syntactically valid while still producing poor documentation.

This issue is intentionally suitable for a first contribution: the expected files, wording, references and validation steps are defined below. No product or architecture decision is required.

Reference implementation

Use the current Nextcloud documentation contribution flow as the main reference:

• https://github.com/nextcloud/documentation/blob/master/CONTRIBUTING.md
• https://github.com/nextcloud/documentation/blob/master/.github/pull_request_template.md
• https://github.com/nextcloud/documentation/blob/master/AGENTS.md

Do not copy unrelated Nextcloud policies or repository-specific release rules.

The relevant behavior to bring to LibreSign is:

1. contributors build the affected documentation locally;
2. documentation-content PRs include a screenshot of the rendered changed or added page(s);
3. visual/layout changes always include screenshots;
4. screenshots help reviewers inspect headings, lists, code blocks, links, images and layout;
5. non-rendered tooling-only changes may mark the screenshot as not applicable with a short explanation.

Files to create or update

1. Create .github/pull_request_template.md

The template must contain these sections.

Resolves / related issue

Ask the contributor to link the issue being addressed.

Screenshots

Use explicit wording similar in meaning to:

Add a screenshot of every changed or added rendered documentation page.

This lets reviewers verify the actual Sphinx output, including headings, lists, code blocks, links, images and layout.

If the pull request changes only non-rendered repository tooling, CI, dependencies or other files that do not affect a documentation page, write Not applicable and explain why.

Do not use vague wording such as only "if applicable" without defining when it is not applicable.

Checklist

Include at least:

• I built the affected documentation locally and reviewed the rendered output.
• I included screenshots of every changed or added rendered documentation page.
• If screenshots are not applicable, this PR changes no rendered documentation and I explained why.
• I checked that headings, lists, code blocks, images and links render correctly.
• I did not include personal data, credentials, private documents or other sensitive information in screenshots.
• I kept the change focused on one documentation concern.

2. Create CONTRIBUTING.md

Keep this file concise and specific to this repository.

It must document:

Repository purpose

Explain that LibreSign/documentation contains the public LibreSign user, administrator and developer documentation.

Documentation areas

Reference the existing manuals:

• user_manual/
• admin_manual/
• developer_manual/
• main/ for top-level navigation

Do not invent a new documentation structure in this issue.

Local validation

Explain how to use the repository's existing build commands. Inspect the current README.rst, Makefile and CI workflow before writing the commands. Do not copy Nextcloud build commands if they differ from this repository.

The contributor guide must require building the affected manual before opening a PR.

Screenshot requirement

State clearly:

• every PR that changes rendered documentation must include screenshots of every changed or newly added rendered page;
• screenshots are review evidence and do not replace the documentation source or automated checks;
• tooling/CI/dependency-only PRs that do not change rendered documentation may state that screenshots are not applicable;
• screenshots must not contain credentials, real personal data, private customer documents, tokens or other sensitive information.

Writing expectations

Point contributors to the existing documentation structure and state these minimum rules:

• describe the product or procedure, not the history of how the change was implemented;
• write for the intended reader of that manual;
• explain concepts before advanced details;
• do not duplicate an existing explanation when a cross-reference is sufficient;
• verify internal links/cross-references;
• keep examples free of real personal or customer data.

Do not create a full style guide in this issue.

DCO

Document the repository's existing DCO requirement consistently with LibreSign contribution rules.

3. Update AGENTS.md

Add only the repository-level rule needed for automated contributors:

• rendered documentation changes require screenshots in the PR;
• screenshots are review evidence;
• sensitive information must not appear in screenshots;
• tooling-only changes can explicitly state that screenshots are not applicable.

Do not copy the complete Nextcloud AGENTS.md.

Screenshot quality

Screenshots should show enough of the rendered page to let a reviewer identify the changed content and surrounding context.

For long pages:

• multiple focused screenshots are acceptable;
• do not require one full-page image when it makes the text unreadable.

For documentation that contains responsive/user-interface examples, capture the viewport relevant to the documented workflow.

Do not add screenshots to the documentation source solely to satisfy this PR-review requirement. PR screenshots are review artifacts unless the documentation itself genuinely needs an image.

Source of truth

Before writing the contribution instructions, inspect:

• README.rst
• Makefile
• .github/workflows/
• existing manual index.rst files
• AGENTS.md

Use the current repository as the source of truth for build commands and structure.

If an existing instruction conflicts with this issue or the actual repository setup, comment on this issue before inventing a new workflow.

Out of scope

Do not:

• restructure the manuals;
• introduce a new documentation framework;
• add a PR preview deployment;
• change Sphinx configuration unless required to fix an error exposed while validating this issue;
• add screenshot automation;
• add image-diff testing;
• copy Nextcloud-specific branch, translation, release or labeling policies;
• modify LibreSign application code.

PR preview deployment is tracked separately by #48.

Validation

Before opening the PR:

1. build the affected documentation using the repository's existing build flow;
2. verify the new PR template renders correctly on GitHub;
3. verify every file/path mentioned in CONTRIBUTING.md exists;
4. verify the contribution instructions do not reference Nextcloud-specific commands that LibreSign does not support;
5. include screenshots of the rendered documentation/contribution page changes in the PR description.

Good first issue

This is a good first issue because the desired behavior and files are already specified.

The contributor does not need to decide:

• whether screenshots are required;
• which documentation manuals exist;
• whether LibreSign should use Sphinx;
• how the documentation architecture should be reorganized;
• how PR preview deployment should work.

The task is to implement the contribution rules above using the current repository as the source of truth.

If the current repository does not provide enough information to write one of the required build instructions, comment on this issue with the exact missing information instead of guessing.

Done when

• .github/pull_request_template.md exists with the required screenshot section and checklist.
• CONTRIBUTING.md documents the repository structure, local validation, screenshot requirement, writing expectations and DCO.
• AGENTS.md contains the screenshot review rule for automated contributors.
• Rendered documentation changes require screenshots of changed/added pages.
• Tooling-only exceptions are explicitly defined.
• Screenshot privacy/safety requirements are documented.
• Existing repository build commands are used rather than copied blindly from Nextcloud.
• The documentation build/checks pass.