Skip to content

Commit fb781e5

Browse files
magicalyakmagicalyak
committed
Add comprehensive Documentation Writer Guide to README - Complete workflow guide for documentation writers - Branch strategy and content placement instructions - Step-by-step tagging and release procedures - Common workflow scenarios with examples - Version activation process for maintainers - Best practices and quick reference commands - Clear guidance on where to place docs for different versions - Instructions for current version updates vs future feature content
1 parent b8489c5 commit fb781e5

File tree

1 file changed

+227
-0
lines changed

1 file changed

+227
-0
lines changed

‎README.md

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,233 @@ Version settings are defined in:
7070

7171
This repository integrates with `netboxlabs-website-dochub` for unified documentation. Version deployments automatically trigger integration updates.
7272

73+
## Documentation Writer Guide
74+
75+
### Understanding the Version Structure
76+
77+
Our documentation follows the NetBox Enterprise release cycle with these version states:
78+
79+
- **Current Version (v1.9)**: Live customer documentation, displayed to users
80+
- **Development Versions (v1.10, v1.11)**: Prepared infrastructure, hidden from users until release
81+
82+
### Branch and Content Strategy
83+
84+
#### Branch Structure
85+
```
86+
main # Latest development (v1.11 content)
87+
├── v1.10 # v1.10 maintenance branch (when ready)
88+
├── v1.9 # v1.9 maintenance branch (current)
89+
└── feature/* # Feature branches for new content
90+
```
91+
92+
#### Where to Write Documentation
93+
94+
| Content Type | Target Branch | When to Use |
95+
|-------------|---------------|-------------|
96+
| **New features for future release** | `main` | Writing docs for v1.11 features |
97+
| **Updates to current release** | `v1.9` | Bug fixes, clarifications for current customers |
98+
| **Preparing next release** | `v1.10` | Writing docs for v1.10 features (when branch exists) |
99+
100+
### Tagging and Release Workflow
101+
102+
#### For Documentation Updates (Most Common)
103+
104+
1. **Current version updates (v1.9)**:
105+
```bash
106+
# Work on v1.9 branch for customer-facing updates
107+
git checkout v1.9
108+
git pull origin v1.9
109+
110+
# Make your documentation changes
111+
# Commit and push changes
112+
git add .
113+
git commit -m "Update installation guide for v1.9"
114+
git push origin v1.9
115+
116+
# Tag the update (increment patch version)
117+
git tag v1.9.3
118+
git push origin v1.9.3
119+
```
120+
**Result**: Documentation automatically deploys to production
121+
122+
2. **Future version content (v1.11)**:
123+
```bash
124+
# Work on main branch for future features
125+
git checkout main
126+
git pull origin main
127+
128+
# Make your documentation changes for new features
129+
# Commit and push changes
130+
git add .
131+
git commit -m "Add documentation for new Jinja2 features in v1.11"
132+
git push origin main
133+
134+
# Don't tag yet - wait for v1.11 release
135+
```
136+
**Result**: Content ready for v1.11 but not visible to customers yet
137+
138+
#### For Major Release Preparation
139+
140+
When preparing a new major/minor version (like v1.10 or v1.11):
141+
142+
1. **Create version branch** (typically done by maintainers):
143+
```bash
144+
# Create new version branch from main
145+
git checkout main
146+
git pull origin main
147+
git checkout -b v1.10
148+
git push origin v1.10
149+
```
150+
151+
2. **Update version configuration** (maintainers):
152+
```bash
153+
# Edit versions.json to move v1.10 from future_versions to versions
154+
# Update default_version if this becomes the new current version
155+
# Commit and push configuration changes
156+
```
157+
158+
3. **Tag the release**:
159+
```bash
160+
git checkout v1.10
161+
git tag v1.10.0
162+
git push origin v1.10.0
163+
```
164+
165+
### Content Guidelines by Version
166+
167+
#### Current Version (v1.9) Content
168+
- **Focus**: Stable, tested features available to customers
169+
- **Updates**: Bug fixes, clarifications, improved examples
170+
- **Avoid**: Documentation for unreleased features
171+
- **Review**: Test all examples and procedures
172+
173+
#### Development Version (v1.11) Content
174+
- **Focus**: New features, major changes, future functionality
175+
- **Updates**: Draft documentation, work-in-progress content
176+
- **Include**: Feature flags, beta warnings if applicable
177+
- **Note**: Content won't be visible to customers until release
178+
179+
### Common Workflows
180+
181+
#### Scenario 1: Fix Documentation Error for Current Customers
182+
```bash
183+
# Customer reports error in v1.9 installation guide
184+
git checkout v1.9
185+
# Fix the error
186+
git commit -m "Fix typo in SSL certificate installation steps"
187+
git push origin v1.9
188+
git tag v1.9.4 # Increment patch version
189+
git push origin v1.9.4
190+
# Documentation automatically updates for customers
191+
```
192+
193+
#### Scenario 2: Document New Feature for Next Release
194+
```bash
195+
# New Jinja2 template feature added to v1.11
196+
git checkout main
197+
# Add comprehensive documentation
198+
git commit -m "Add Jinja2 conditional logic documentation"
199+
git push origin main
200+
# Content staged for v1.11 release, not visible to customers yet
201+
```
202+
203+
#### Scenario 3: Backport Important Update
204+
```bash
205+
# Important security update applies to both v1.9 and v1.11
206+
git checkout v1.9
207+
# Make the update
208+
git commit -m "Add security best practices for LDAP configuration"
209+
git push origin v1.9
210+
git tag v1.9.5
211+
git push origin v1.9.5
212+
213+
# Also apply to future version
214+
git checkout main
215+
git cherry-pick <commit-hash>
216+
git push origin main
217+
```
218+
219+
### Version Activation Process
220+
221+
When a development version becomes ready for customers:
222+
223+
#### Step 1: Update Configuration
224+
Edit `versions.json`:
225+
```json
226+
{
227+
"versions": [
228+
{
229+
"version": "v1.10",
230+
"branch": "v1.10",
231+
"title": "v1.10 (Latest)",
232+
"default": true,
233+
"status": "latest"
234+
},
235+
{
236+
"version": "v1.9",
237+
"branch": "v1.9",
238+
"title": "v1.9 (Stable)",
239+
"status": "stable"
240+
}
241+
],
242+
"default_version": "v1.10"
243+
// Move v1.10 from future_versions to versions array
244+
}
245+
```
246+
247+
#### Step 2: Update Other Files
248+
- `mkdocs.yml`: Add v1.10 to available versions
249+
- `.github/workflows/version-deploy.yml`: Update LATEST_VERSION
250+
- `README.md`: Update current versions list
251+
252+
#### Step 3: Test and Deploy
253+
```bash
254+
git add .
255+
git commit -m "Activate v1.10 for customer access"
256+
git push origin main
257+
```
258+
259+
### Best Practices
260+
261+
#### ✅ **Do:**
262+
- Test all code examples before committing
263+
- Use clear, descriptive commit messages
264+
- Tag immediately after pushing customer-facing changes
265+
- Keep development content in appropriate branches
266+
- Review changes in the context of the target version
267+
268+
#### ❌ **Don't:**
269+
- Tag development versions (main branch) until ready for release
270+
- Mix current customer fixes with future feature documentation
271+
- Forget to increment version numbers in tags
272+
- Skip testing examples in the target version environment
273+
274+
### Getting Help
275+
276+
- **Version questions**: Check `versions.json` for current configuration
277+
- **Branch questions**: Use `git branch -a` to see all available branches
278+
- **Tag questions**: Use `git tag -l` to see existing version tags
279+
- **Integration questions**: Contact the dochub team for unified site issues
280+
281+
### Quick Reference Commands
282+
283+
```bash
284+
# Check current version configuration
285+
cat versions.json
286+
287+
# See all available branches
288+
git branch -a
289+
290+
# See all version tags
291+
git tag -l | sort -V
292+
293+
# Check which version branch you're on
294+
git branch --show-current
295+
296+
# See recent version deployments
297+
git log --oneline --grep="v1\."
298+
```
299+
73300
## :warning:
74301

75302
If you see errors like this...

0 commit comments

Comments
 (0)