Proposal: English Plugin Development Book – Chapter 8 (Improve Config Mapping & DX)

[vedantlavale]

I've been exploring the Plugin Development Book (currently hosted on Zenn in Japanese) and reviewing how it could be adapted into the PipeCD docs as part of the LFX project.
While going through the content, I noticed a key onboarding gap around how plugin configuration (YAML) maps to Go structs, which can be confusing for new contributors.

---

Problem
The current material introduces configuration and implementation separately, but doesn't clearly connect:

• Go struct fields
• JSON/YAML tags
• The actual YAML config written by users

This makes it harder for new developers to understand how their plugin code and configuration interact.
For example, when a user writes:

apiVersion: pipecd.dev/v1beta1
kind: Kubernetes
spec:
  inputs:
    namespace: my-app
    image: nginx:latest

It's not immediately clear how namespace and image map to the corresponding Go struct fields with their JSON tags like json:"image".

---

Proposal
I'd like to contribute an improved English version of Chapter 8 with a focus on developer experience, including:

• A side-by-side example (Go struct ↔ YAML config) showing field-by-field mapping
• A clear mental model of how config flows from YAML → Go struct
• Common pitfalls (e.g., field/tag mismatches, nesting confusion, case sensitivity)
• Small best-practice notes to guide new contributors

---

Recommended Location
Based on the current repo structure, I recommend adding to the docs-dev section (work-in-progress/new features):

docs/content/en/docs-dev/plugin/
├── _index.md              # Plugin development overview
├── configuration.md       # Go struct ↔ YAML mapping (new)
├── implementation.md      # Implementation guide
├── deployment.md          # Deployment stages
└── testing.md             # Testing guide

Alternatively, since pkg/plugin/sdk/README.md points to the separatepiped-plugin-sdk-gorepository, it could also live there under docs/ once synced.

---

How to Implement

1. Check existing plugin docs: The SDK README points to https://github.com/pipe-cd/piped-plugin-sdk-go - we should ensure alignment
2. Create config mapping doc: Add configuration.md to docs/content/en/docs-dev/plugin/
3. Follow existing doc patterns: Use front-matter like other docs in docs-dev/
4. Add to navigation: Update docs/content/en/docs-dev/_index.md to include plugin section
   The chapter-by-chapter incremental approach would work well - starting with just the configuration mapping as a focused first contribution.

---

Goal
Make plugin development easier to understand for first-time contributors and improve onboarding as part of the Plugin Development Book effort.

---

If this direction aligns, I can start with a draft and open a PR for review.
Would also appreciate guidance on:

• Preferred location/structure for integrating these chapters into the docs
• Whether a chapter-by-chapter incremental approach is preferred
• Any existing plugin documentation standards I should follow
  Thanks!