Skip to content

Commit 509dcfd

Browse files
luisjguedesluisjguedes
committed
Initial commit
0 parents  commit 509dcfd

35 files changed

+888
-0
lines changed

‎.gitattributes‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Auto detect text files and perform LF normalization
2+
* text=auto

‎.github/workflows/ci.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [ "main" ]
7+
8+
jobs:
9+
quality:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout
13+
uses: actions/checkout@v4
14+
15+
- name: Set up Python
16+
uses: actions/setup-python@v5
17+
with:
18+
python-version: "3.11"
19+
20+
- name: Install Python dependencies
21+
run: |
22+
python -m pip install --upgrade pip
23+
pip install -r requirements.txt
24+
pip install -r requirements-docs.txt
25+
26+
- name: Validate prompt library
27+
run: |
28+
python -m docsai_toolkit validate-prompts
29+
30+
- name: Validate evaluation dataset (dry-run)
31+
run: |
32+
python -m docsai_toolkit eval --dataset eval/datasets/smoke.yml --dry-run
33+
34+
- name: Build MkDocs site (strict)
35+
run: |
36+
mkdocs build --strict
37+
38+
- name: Lint prose with Vale
39+
uses: errata-ai/vale-action@v2
40+
with:
41+
files: docs
42+
vale_flags: "--glob=*.md"
43+
fail_on_error: true

‎.github/workflows/pages.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Deploy Docs Site
2+
3+
on:
4+
push:
5+
branches: [ "main" ]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: "pages"
15+
cancel-in-progress: true
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v4
23+
24+
- name: Set up Python
25+
uses: actions/setup-python@v5
26+
with:
27+
python-version: "3.11"
28+
29+
- name: Install docs dependencies
30+
run: |
31+
python -m pip install --upgrade pip
32+
pip install -r requirements-docs.txt
33+
34+
- name: Build site
35+
run: |
36+
mkdocs build --strict --site-dir site
37+
38+
- name: Upload Pages artifact
39+
uses: actions/upload-pages-artifact@v3
40+
with:
41+
path: site
42+
43+
deploy:
44+
needs: build
45+
runs-on: ubuntu-latest
46+
environment:
47+
name: github-pages
48+
url: ${{ steps.deployment.outputs.page_url }}
49+
steps:
50+
- name: Deploy to GitHub Pages
51+
id: deployment
52+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*.pyo
5+
*.pyd
6+
*.egg-info/
7+
dist/
8+
build/
9+
.venv/
10+
.env
11+
.env.*
12+
.pytest_cache/
13+
14+
# MkDocs
15+
site/
16+
17+
# OS
18+
.DS_Store
19+
Thumbs.db

‎.vale.ini‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
StylesPath = styles
2+
3+
MinAlertLevel = suggestion
4+
5+
[*.md]
6+
BasedOnStyles = DocsAI

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Docs AI Operating Model (template)
2+
3+
A **docs-as-code + LLM strategy** reference implementation you can fork to bootstrap:
4+
- a documentation site (MkDocs)
5+
- a PromptOps library (prompts as code, with review + validation)
6+
- an evaluation harness (quality gates for AI-assisted writing)
7+
- a governance pack (policies, risk register, ADRs, metrics)
8+
9+
> **Portfolio note**
10+
>
11+
> All content in this repository is **generic and non-proprietary**. It is meant to demonstrate senior-level thinking and execution for documentation leaders and AI-forward technical writers.
12+
13+
---
14+
15+
## Why this repo exists
16+
17+
Docs teams are being asked to “use AI” — but the real work is:
18+
- **deciding** which problems are worth solving with LLMs
19+
- **controlling risk** (privacy, hallucinations, IP, compliance)
20+
- **operationalizing quality** (repeatable evaluation, measurable outcomes)
21+
- **integrating into DocsOps** (CI/CD, style gates, review workflows)
22+
23+
This repo is designed to **show your seniority** by making those decisions visible.
24+
25+
---
26+
27+
## What it demonstrates
28+
29+
### Docs-as-code (DocsOps)
30+
- Site authored in Markdown and published with MkDocs
31+
- CI quality gates: build checks + prose linting
32+
- A consistent information architecture (strategy → governance → implementation → case studies)
33+
34+
### LLM strategy (operating model)
35+
- Use-case catalog + decision criteria
36+
- Guardrails: data classification, risk register, human review lanes
37+
- Metrics: adoption, quality, efficiency, and customer impact
38+
39+
### PromptOps (prompts as code)
40+
- Prompt files stored with metadata and versioning
41+
- Schema validation in CI (no broken prompt definitions)
42+
- Patterns for prompt structure and output contracts
43+
44+
### Evaluation (what “good” means)
45+
- Task-based evaluation dataset (small but realistic)
46+
- Rule-based checks for structure + safety
47+
- Optional “LLM-as-judge” extension points (vendor-agnostic)
48+
49+
---
50+
51+
## Quick start (local)
52+
53+
```bash
54+
# 1) Create and activate a virtual environment
55+
python -m venv .venv
56+
source .venv/bin/activate
57+
58+
# 2) Install deps
59+
pip install -r requirements.txt
60+
pip install -r requirements-docs.txt
61+
62+
# 3) Validate the prompt library
63+
python -m docsai_toolkit validate-prompts
64+
65+
# 4) Build the site (strict)
66+
mkdocs build --strict
67+
68+
# 5) Run a lightweight evaluation pass
69+
python -m docsai_toolkit eval --dataset eval/datasets/smoke.yml --dry-run
70+
```
71+
72+
---
73+
74+
## Publish the docs site (GitHub Pages)
75+
76+
This repo includes a Pages workflow that:
77+
1) builds the MkDocs site
78+
2) uploads it as a Pages artifact
79+
3) deploys it via `actions/deploy-pages`
80+
81+
In your repo settings:
82+
- **Settings → Pages → Source → GitHub Actions**
83+
84+
---
85+
86+
## Repository map
87+
88+
```
89+
docs/ # the published site (strategy, governance, implementation)
90+
prompts/ # prompt library (YAML)
91+
eval/ # evaluation datasets + rubrics
92+
adr/ # architecture decision records
93+
src/docsai_toolkit/ # small CLI utilities (validation + eval scaffolding)
94+
.github/workflows/ # CI + Pages deployment
95+
styles/ # Vale prose linting rules (optional but recommended)
96+
```
97+
98+
---
99+
100+
## Suggested ways to personalize (for hiring impact)
101+
102+
- Add a **case study** reflecting your strongest domain (SaaS, MDM, APIs, data governance)
103+
- Add a **short demo video** (60–90s) showing: PR → CI → Pages → prompt validation → eval report
104+
- Add a “**Hiring?**” section with your role targets and preferred work style (remote-first, async)
105+
106+
---
107+
108+
## License
109+
110+
MIT (see `LICENSE`).

‎adr/adr-0001-pages-workflow.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# ADR-0001: Use GitHub Pages with a custom workflow
2+
3+
## Status
4+
Accepted
5+
6+
## Context
7+
We want a documentation site that:
8+
- is easy to publish
9+
- is reviewable via pull requests
10+
- supports automated quality gates
11+
12+
## Decision
13+
Use **GitHub Pages** with a custom GitHub Actions workflow:
14+
- build MkDocs into a static site
15+
- upload as a Pages artifact
16+
- deploy with `actions/deploy-pages`
17+
18+
## Consequences
19+
- Requires Pages to be configured with **Source = GitHub Actions**
20+
- CI must set permissions for Pages deployment (OIDC + pages write)
21+

‎docs/adr/adr-0001-pages-workflow.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# ADR-0001: Use GitHub Pages with a custom workflow
2+
3+
## Status
4+
Accepted
5+
6+
## Context
7+
We want a documentation site that:
8+
- is easy to publish
9+
- is reviewable via pull requests
10+
- supports automated quality gates
11+
12+
## Decision
13+
Use **GitHub Pages** with a custom GitHub Actions workflow:
14+
- build MkDocs into a static site
15+
- upload as a Pages artifact
16+
- deploy with `actions/deploy-pages`
17+
18+
## Consequences
19+
- Requires Pages to be configured with **Source = GitHub Actions**
20+
- CI must set permissions for Pages deployment (OIDC + pages write)
21+

‎docs/adr/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Architecture Decision Records
2+
3+
ADRs record *why* you made a choice (tradeoffs, constraints, consequences).
4+
5+
- [ADR-0001 Pages workflow](adr-0001-pages-workflow.md)
6+

0 commit comments

Comments
 (0)