RailWise KB已发布

RailWise Knowledge Base Contribution Guide

Guidelines for contributing to the RailWise knowledge base, including submission process, review criteria, content quality standards, and recognition system

复核 2026-07-09入门公开可引用RailWise 技术团队

learning-path

RailWise Knowledge Base Contribution Guide

Welcome to the RailWise Knowledge Base Contributor Community!

This guide will help you understand how to contribute high-quality technical documentation, share your engineering experience, and collaborate with engineers worldwide.

1. Why Contribute

The RailWise Knowledge Base is an open technical documentation platform maintained by the RailWise Technical Documentation Team and the community. Your contributions can:

Share practical experience: Document your unique project cases, solutions, and lessons learned
Help fellow engineers: Your documentation may solve problems for engineers in similar scenarios
Build professional reputation: High-quality contributors are recognized in the community and industry
Improve products: Feedback and documentation help RailWise products continuously evolve

2. What to Contribute

2.1 Content Types

Content Type	Description	Examples
Project Cases	Real-world engineering project documentation	Shield tunneling monitoring case, deep excavation protection zone case
Technical Tutorials	Step-by-step operation guides	TSM platform configuration tutorial, CLI workflow writing tutorial
Standard Interpretations	Engineering standards AI interpretation	GB 50497 clause interpretation, JGJ 8 precision analysis
Tool Scripts	Code, scripts, and tools	Python data processing script, automated monitoring configuration template
FAQ & Troubleshooting	Problem solutions and experience summaries	Common instrument errors, data anomaly handling
Industry Insights	Technology trends and industry analysis	AI monitoring technology trends, digital twin applications

2.2 Content Requirements

All contributed content must meet the following requirements:

Accuracy: Technical content must be accurate, with verifiable data and sources
Practicality: Content should be actionable, not purely theoretical
Completeness: Documents should have clear structure, including background, methods, results, and conclusions
Standardization: Follow RailWise knowledge base document format specifications (see Section 4)
Originality: Prioritize original content; for referenced content, clearly indicate sources

3. Contribution Process

3.1 Contribution Workflow

┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│  Idea   │ → │  Draft  │ → │  Submit │ → │  Review │ → │ Publish │
└─────────┘    └─────────┘    └─────────┘    └─────────┘    └─────────┘
     │              │              │              │              │
     ↓              ↓              ↓              ↓              ↓
  Identify      Write         PR / Email     Technical       Public
  topic         content       submission     review          release

3.2 Submission Methods

Method 1: GitHub Pull Request (Recommended)

Fork the RailWise Docs repository
Create a new branch: git checkout -b contributor/your-name/topic
Write content following document specifications
Submit Pull Request with detailed description
Wait for technical review and feedback
Modify based on feedback until merged

Method 2: Email Submission

Send your document to: docs@railwise.cn

Email format:

Subject: [Contribution] Document Title - Contributor Name

Body:
- Document type: [Case/Tutorial/Standard Interpretation/Tool/FAQ/Industry Insight]
- Applicable scenario: [Which engineering scenario does this document apply to]
- Key points: [3-5 core points]
- Attachment: [Document file, supporting images, code files]

Method 3: Community Forum

Post your content on the RailWise Community Forum, and the documentation team will periodically select high-quality content for inclusion in the knowledge base.

4. Document Format Specifications

4.1 File Naming Convention

[type]-[topic]-[language].md

Examples:
- case-shield-crossing-bridge.md          # Case — Shield crossing bridge
- tutorial-tsm-station-config.md          # Tutorial — TSM station configuration
- standard-gb50497-interpretation.md      # Standard — GB 50497 interpretation
- tool-python-data-processing.md          # Tool — Python data processing
- faq-cli-common-errors.md              # FAQ — CLI common errors

4.2 YAML Frontmatter Requirements

Every document must include complete YAML Frontmatter at the beginning:

---
title: "Document Title"
description: "Concise document description, 50-200 characters"
category_primary: "Primary Category"
category_secondary: "Secondary Category"
tags: ["tag1", "tag2", "tag3"]
author: "Contributor Name / Organization"
date: "YYYY-MM-DD"
version: "1.0.0"
applicable_scenarios: ["Applicable scenario 1", "Applicable scenario 2"]
standard_refs: ["GB XXXXX-YYYY", "JGJ X-YYYY"]
---

4.3 Content Structure Requirements

# Document Title

> **Reading Time**: X minutes
> **Target Audience**: [Who is this document for]

## 1. Overview / Background

## 2. Main Content

### 2.1 Subsection

#### 2.1.1 Detailed Content

- Use lists, tables, and code blocks to organize content
- Include :::tip :::warning :::info prompt boxes for key points

## 3. Examples / Cases

## 4. Common Issues

## 5. Related Documents

- [Related Document 1](./relative-path.md)
- [Related Document 2](./relative-path.md)

## 6. Metadata Tags

<meta name="ai-tags" content="tag1, tag2, tag3" />

5. Review Criteria

5.1 Technical Review Checklist

Review Item	Criteria	Weight
Technical Accuracy	Content technically correct, no errors	30%
Practical Value	Content can guide actual engineering operations	25%
Completeness	Document structure complete, covering all necessary content	20%
Format Standardization	Complies with document format specifications	15%
Language Quality	Clear expression, professional terminology accurate	10%

5.2 Review Process

Automated Check: Format validation, link check, code syntax check
Technical Review: Domain expert reviews technical accuracy
Editorial Review: Documentation team reviews language and format
Final Confirmation: Author confirms modifications, ready for publication

Typical review cycle: 3-7 business days

6. Contributor Recognition System

6.1 Contribution Points

Contribution Type	Points	Description
New document	50-200 points	Based on document length, depth, and quality
Document update	10-50 points	Based on update scope
Bug fix / Error correction	5-20 points	Per correction
Translation	30-100 points	Based on document length and language difficulty
Code contribution	20-100 points	Based on code complexity and utility

6.2 Contributor Levels

Level	Points Required	Benefits
Bronze Contributor	100 points	Contributor badge, priority technical support
Silver Contributor	500 points	Silver badge, quarterly gift package, new feature early access
Gold Contributor	2000 points	Gold badge, annual conference invitation, product discount
Platinum Contributor	5000 points	Platinum badge, annual dinner invitation, exclusive consultant status
Diamond Contributor	10000 points	Diamond badge, RailWise annual outstanding contributor award

6.3 Outstanding Contributor Cases

Case 1: Engineer Zhang — Deep Excavation Monitoring Expert

Contribution: 12 deep excavation monitoring cases, 5 standard interpretation documents
Total points: 3,500 points
Recognition: Gold Contributor, invited to 2025 RailWise Technical Summit as speaker
Quote: “Sharing experience is the best way to improve oneself. Through documentation, I not only helped others but also systematically organized my own knowledge.”

Case 2: Team “Shield Guardian” — Shield Tunneling Monitoring Team

Contribution: Complete shield tunneling monitoring series (8 documents), 3 tool scripts
Total points: 2,800 points (team)
Recognition: Team Gold Contributor, featured in RailWise official blog
Impact: Documents have been referenced by 500+ engineers, significantly improving shield tunneling monitoring standardization

7. Content Quality Standards

7.1 Data Usage Standards

Real project data: Must be de-sensitized, no client names, specific locations, or personnel information
Typical values: When using typical values, clearly label “Typical Value” or “Example Data”
Calculation formulas: Must include complete derivation process and parameter explanations
Code examples: Must be runnable, with necessary comments and error handling

7.2 Image & Chart Standards

Images must be clear, with resolution not lower than 1920×1080
Charts must have complete legends, axis labels, and units
Schematic diagrams should use unified symbols and line styles
Screenshots should not contain sensitive information

7.3 Citation Standards

National standards: GB XXXXX-YYYY format
Industry standards: JGJ/CJJ/T X-YYYY format
Academic papers: Author. Title. Journal/Conference, Year
Online resources: URL + access date

8. Frequently Asked Questions

Q1: Can I contribute content in English?

A: Yes. RailWise Knowledge Base welcomes multilingual contributions. Currently supported languages: Chinese (Simplified), English. Documents in other languages will be considered based on community demand.

Q2: Do I retain copyright of contributed content?

A: Contributors retain original copyright. By contributing, you grant RailWise a non-exclusive license to use, modify, and distribute the content within the knowledge base.

Q3: How long does review typically take?

A: Automated checks complete within 24 hours. Technical review typically takes 3-7 business days. Complex documents may require extended review time.

Q4: Can I contribute content about competing products?

A: The knowledge base focuses on RailWise products and general engineering surveying/monitoring technologies. Content about competing products is not accepted unless for technical comparison in an objective, neutral manner.

Q5: How to report errors in existing documents?

A: You can:

Submit an Issue on GitHub
Send email to docs@railwise.cn
Post in the community forum
Click “Edit this page” at the bottom of the document to submit a correction PR

9. Contact Us

Contribution Email: docs@railwise.cn
Technical Support: support@railwise.cn
Community Forum: https://community.railwise.cn
GitHub: https://github.com/railwise/docs
WeChat Work: Scan QR code on official website to join contributor group