[PBI] Administrator User Documentation

[cjlapao]

Description

Write the full end-user documentation for the Parallels DevOps Jenkins plugin targeting Jenkins administrators. This covers architecture concepts, installation options (Plugin Manager + manual .hpi), full configuration reference, Host vs Orchestrator mode explanation, agent template field reference, and operational guidance (monitoring, scaling, cost control). This document will be published to the jenkinsci plugin wiki or the plugin's GitHub Pages site.

User Story

As a Jenkins administrator at an organisation using Parallels, I want comprehensive documentation for the Parallels DevOps plugin so that I can configure, operate, and troubleshoot dynamic VM agent provisioning without needing to read the plugin source code.

Acceptance Criteria

• Architecture overview section: Explains the dynamic provisioning concept, the role of prl-devops-service, and a high-level diagram of the provision → connect → build → terminate lifecycle.
• Installation section: Covers both plugin sources (Jenkins Update Center one-click install once published, and manual .hpi upload).
• Configuration reference: A complete table of every configurable field on PrlDevopsCloud and AgentTemplate with name, type, default, and description.
• Connection mode guide: Explains Host API vs Orchestrator mode — when to use each, what permissions/credentials each requires, and any behavioural differences.
• Label-based job routing: Explains how Jenkins labels on templates are used to route jobs; includes an example with two templates and two job types.
• Retention policy guide: Explains ONE_SHOT vs IDLE_TIMEOUT with diagrams or flowcharts; guidance on when to use each (cost optimisation vs developer experience).
• Monitoring & operations: How to see provisioned agents in the Jenkins Nodes view, how to manually terminate a stuck agent, and how to verify cleanup happened via the prl-devops-service.
• Security considerations: How credentials are stored (Jenkins Credentials Plugin), SSH key best practices, network requirements (Jenkins master → DevOps Service, Jenkins master → VM IP).
• FAQ: At least 8 questions covering common operational queries.
• Document published: Hosted at docs/admin-guide.md in the repo; linked from README.md; optionally published to GitHub Pages or the Jenkins plugin wiki.

Definition of Done

• Code implemented following best practices.
• Unit tests written and passing.
• Code reviewed and approved.
• Merged into the main branch.
• Documentation updated (if applicable).
• Deployed to staging/production environment.

Assumptions and Constraints

• Assumption 1: Documentation is in English; localisation is out of scope.
• Assumption 2: The author has access to a working plugin + prl-devops-service instance to verify steps during writing.
• Constraint 1: This is documentation only — no code changes.
• Constraint 2: The document must be reviewed by at least one person who was not involved in writing the plugin (from a "fresh admin" perspective).

Dependencies

No response

Additional Notes

Suggested document structure

# Parallels DevOps Service — Jenkins Cloud Plugin

## Overview
  ### How it works (lifecycle diagram)
  ### Requirements

## Installation
  ### From Jenkins Update Center
  ### Manual .hpi install

## Configuration
  ### Cloud Provider Settings (field reference table)
  ### Connection Modes: Host API vs Orchestrator
  ### Agent Templates (field reference table)

## Job Configuration
  ### Assigning jobs to Parallels agents (labels)
  ### Example: Multi-template setup

## Retention Policies
  ### ONE_SHOT
  ### IDLE_TIMEOUT
  ### Choosing the right policy

## Operations & Monitoring
  ### Viewing active agents
  ### Manually terminating a VM
  ### Verifying cleanup

## Security
  ### Credentials storage
  ### Network requirements
  ### SSH key recommendations

## FAQ
## Changelog