Developer Documentation Contribution Guide
This guide is for developers participating in the RNOH community documentation collaboration. It standardizes documentation writing, classification, bilingual synchronization, and submission processes to ensure consistent quality and efficient maintenance.
1. Directory Structure
Documentation is organized by Developer Journey, covering the full lifecycle from design to operations:
Directory and Developer Journey Mapping
| Directory | Journey Stage | Core Content | Version-Related |
|---|---|---|---|
01-design |
Design | Interface specs, architecture planning, communication | ❌ |
02-development |
Development | Environment setup, feature development, components | ✅ partial |
03-debugging |
Debugging | Debugging methods, troubleshooting, FAQ | ❌ |
04-optimization |
Optimization | Performance tuning, practice cases | ❌ |
05-operations |
Operations | Version management, stability management, build & bundling | ✅ |
06-community |
Community Governance | Guidelines, contribution guides, roadmap | ❌ |
Version-Related Document Marking
These documents need to be updated with each release:
| Directory | Version-Related Files |
|---|---|
02-development |
environment-setup.md, SDK version configuration guide.md |
05-operations |
release-notes-overview.md, version-upgrade-guide.md, release-notes/, rn-js-bundle.md |
2. Documentation Writing Standards
File Naming Convention
| Rule | Chinese | English |
|---|---|---|
| Filename | Chinese, no spaces, use hyphens | Lowercase English, use hyphens |
| Encoding | UTF-8 without BOM | UTF-8 without BOM |
| Format | Markdown (.md) | Markdown (.md) |
Examples:
- Chinese:
版本升级指导.md,调试调测.md - English:
version-upgrade-guide.md,debugging.md
Document Header Template
Each document must include the following metadata:
# Document Title
> Applicable versions: v0.72 / v0.77 / v0.82 / v0.84 (required for version-related docs)
> Developer Journey: Design / Development / Debugging / Optimization / Testing / Operations
> Last updated: YYYY-MM-DD
> Contributors: @username
## Overview
Brief description of document purpose and applicable scenarios.
Content Writing Requirements
| Requirement | Description |
|---|---|
| Heading levels | Maximum 4 levels (# → ## → ### → ####), no skipping |
| Paragraph length | Maximum 5 lines per paragraph |
| Code examples | Must specify language, provide complete runnable examples |
| Image standards | Store in ../figures/ directory, use relative paths |
| Link standards | Prefer relative paths, external links need source attribution |
3. Bilingual Documentation Standards
Bilingual File Correspondence
| Chinese File | English File | Location |
|---|---|---|
docs/zh-cn/01-设计/架构介绍.md |
docs/en/01-design/architecture.md |
Same directory level |
Bilingual Synchronization Requirements
| Requirement | Description |
|---|---|
| Content consistency | Core technical content must be fully synchronized |
| Timely updates | English version must be updated within 7 days after Chinese update |
| Mark differences | If Chinese has localized content, mark it in English version |
New Document Process
- Write Chinese version first, store in
docs/zh-cn/<directory>/ - Create English version synchronously, store in
docs/en/<directory>/ - Update both README.md navigation files with new document links
- Document bilingual sync status in PR
4. Document Classification Criteria
Classification by Developer Journey
When adding new documents, determine the directory by these criteria:
| Journey Stage | Criteria | Directory |
|---|---|---|
| Design | Interface specs, architecture principles, communication mechanisms, technical planning | 01-design |
| Development | Environment setup, feature development, component customization, development guides | 02-development |
| Debugging | Debugging tools, troubleshooting methods, FAQ, error resolution guides | 03-debugging |
| Optimization | Performance tuning methods, optimization cases, performance analysis | 04-optimization |
| Operations | Version management, stability management, build & bundling, deployment, fix history archiving | 05-operations |
| Community | Community guidelines, contribution guides, roadmap, contribution processes | 06-community |
Version Relevance Determination
After determining the journey directory, further assess version relevance:
| Criterion | Version-Related | Example |
|---|---|---|
| Contains version numbers | ✅ | version-upgrade-guide.md |
| SDK version dependency | ✅ | SDK version configuration guide.md |
| API version changes | ✅ | RN upgrade adaptation.md |
| Release records | ✅ | release-notes/ |
| Fix history archiving | ✅ | 0.82-stability-fixes/ |
| Principles & methods | ❌ | architecture.md, debugging.md |
| Standards & guidelines | ❌ | community-issue-guidelines.md |
5. Document Submission Process
Pre-submission Checklist
| Check Item | Description |
|---|---|
| Journey directory | Document in correct journey directory |
| Version marking | Version-related documents marked with applicable versions |
| File naming | Follows naming convention |
| Bilingual sync | English version created/updated |
| Navigation update | README.md navigation updated |
| Valid links | Internal links work correctly |
| Image paths | Image reference paths correct |
PR Submission Standards
-
Title format:
docs: add/update/fix [journey stage] [document name]Examples:
docs: add development multi-screen adaptation guidedocs: update operations version upgrade guide for v0.82docs: fix debugging FAQ link error
-
Description template:
## Change Description - [Added/Updated/Fixed] document: xxx - Developer Journey: Design / Development / Debugging / Optimization / Testing / Operations / Community - Version-related: Yes / No - Bilingual sync: English version synced / pending ## Checklist - [x] Correct journey directory - [x] Complete version marking - [x] Proper file naming - [x] Bilingual sync completed - [x] README navigation updated - [x] Valid link paths -
Link Issues: If related issues exist, link them in PR
6. Document Review Standards
Review Dimensions
| Dimension | Standard |
|---|---|
| Accuracy | Technical content correct, code examples runnable |
| Completeness | Content covers topic fully, no key info missing |
| Standards | Follows naming, format, bilingual sync standards |
| Readability | Clear structure, concise language, easy to understand |
| Timeliness | Version-related content is current |
| Journey match | Document content matches its journey directory |
Review Process
- Self-check by submitter → All checklist items pass
- Community review → At least 1 documentation reviewer approves
- Merge → Merge to main branch after approval
7. FAQ
Q1: How to determine which directory a document belongs to?
By developer journey:
- Design stage outputs →
01-design - Development process needs →
02-development - Debugging & troubleshooting →
03-debugging - Performance optimization →
04-optimization - Version operations →
05-operations - Community guidelines →
06-community
Q2: What if Chinese version cannot be synced immediately?
Mark "pending sync" in PR and add to English document header:
> Chinese version pending sync, community translation contributions welcome
Q3: How to store images?
Store in ../figures/ directory at same or parent level:
Q4: How to update README navigation?
In the corresponding language's README.md:
- Add entry in "Developer Journey Navigation" table
- Add file location in "Directory Structure" tree
Q5: When to update version-related documents?
| Document Type | Update Timing |
|---|---|
| Release notes | On release day |
| Upgrade guides | On release day |
| SDK configuration | When SDK version changes |
| Fix history archiving | Within one week after release |
8. Contributor Recognition
| Contribution Type | Recognition Method |
|---|---|
| Adding core documents | Document signature + Community contributor badge |
| Bilingual sync contributions | Translation contributor badge |
| Continuous documentation maintenance | Documentation maintainer badge |
| Timely version document updates | Version maintainer badge |
Appendix: Directory Quick Reference
| Directory | Journey Stage | Version-Related | Core Content |
|---|---|---|---|
| 01-design | Design | ❌ | Architecture, principles, specs |
| 02-development | Development | ✅ partial | Environment, features, components, scenarios |
| 03-debugging | Debugging | ❌ | Debugging, troubleshooting, FAQ |
| 04-optimization | Optimization | ❌ | Performance, practice cases |
| 05-operations | Operations | ✅ | Version, build, stability, fix archiving |
| 06-community | Community Governance | ❌ | Guidelines, roadmap |
For questions, raise an issue in the community or contact documentation maintainers.