Contributing to Tresor Knowledge Center

Thank you for your interest in contributing to our knowledge center! This guide will help you understand how to contribute effectively.

How to Contribute

We welcome contributions in many forms:

  • 📝 Adding new documentation
  • 🔄 Updating existing content
  • 🐛 Fixing errors or typos
  • 💡 Sharing new insights and best practices
  • 🖼️ Adding diagrams and visual aids

Getting Started

1. Set Up Your Environment

# Clone the repository
git clone https://github.com/tresor/knowledge-center.git
cd knowledge-center

# Install dependencies
npm install

# Start local GitBook server
npm start

2. Find Something to Work On

  • Check existing Issues
  • Look for [TODO] markers in documentation
  • Identify outdated content
  • Add missing documentation

Contribution Process

1. Create a Branch

# Update main branch
git checkout main
git pull origin main

# Create feature branch
git checkout -b docs/your-topic-name

2. Make Your Changes

Follow our documentation standards:

  • Use clear, concise language
  • Include code examples where relevant
  • Add diagrams for complex concepts
  • Update the SUMMARY.md if adding new pages

3. Test Your Changes

# Build and preview locally
npm run gitbook:serve

# Check for broken links
npm run check-links

# Validate Markdown
npm run lint:md

4. Submit a Pull Request

  1. Push your branch to GitHub
  2. Create a Pull Request with:
    • Clear title describing the change
    • Description of what was added/changed
    • Link to related issues (if any)
    • Screenshots (if UI changes)

Documentation Standards

File Naming

  • Use lowercase with hyphens: my-document-name.md
  • Be descriptive but concise
  • Group related files in folders

Markdown Style Guide

Headings

# Main Title (H1 - One per document)

## Section Title (H2)

### Subsection Title (H3)

#### Minor Section (H4)

Code Blocks

Always specify the language:

​```javascript
const example = "Use language identifiers";
​


#### Links
- Use relative links for internal documents
- Use full URLs for external resources
```markdown
[Internal Link](../guides/example.md)
[External Link](https://example.com)

Images

![Alt text describing the image](../assets/images/example.png)

Content Guidelines

Writing Style

  • Be Clear: Use simple, direct language
  • Be Concise: Get to the point quickly
  • Be Consistent: Follow existing patterns
  • Be Helpful: Anticipate reader questions

Structure

  1. Start with an overview/introduction
  2. Use bullet points for lists
  3. Include examples and use cases
  4. Add troubleshooting sections where relevant
  5. End with resources or next steps

Code Examples

  • Provide working, tested code
  • Include comments for clarity
  • Show both good and bad examples
  • Keep examples focused and minimal

Metadata

Add frontmatter to documents when needed:

---
title: Document Title
description: Brief description for SEO
author: Your Name
date: 2024-01-01
tags: [tag1, tag2]
---

Types of Contributions

New Documentation

When adding new documentation:

  1. Check if similar content exists
  2. Choose the appropriate section
  3. Follow the template structure
  4. Update SUMMARY.md
  5. Add cross-references to related docs

Updates and Improvements

When updating existing docs:

  1. Verify information accuracy
  2. Update code examples to latest versions
  3. Add missing information
  4. Improve clarity and structure
  5. Update last modified date

Technical Writing Tips

For Tutorials

  1. State the goal upfront
  2. List prerequisites
  3. Use numbered steps
  4. Include expected outcomes
  5. Add troubleshooting section

For Reference Documentation

  1. Use consistent formatting
  2. Include all parameters/options
  3. Provide usage examples
  4. Document edge cases
  5. Add version information

For Conceptual Documentation

  1. Start with the big picture
  2. Use analogies when helpful
  3. Include diagrams
  4. Build complexity gradually
  5. Summarize key points

Review Process

What We Look For

  • Accuracy: Information is correct and tested
  • Clarity: Easy to understand
  • Completeness: Covers the topic adequately
  • Consistency: Follows our style guide
  • Value: Adds useful information

Review Timeline

  • Initial review: Within 2-3 business days
  • Feedback incorporation: As needed
  • Final approval: 1-2 days after changes

Tools and Resources

  • Markdown Editor: VS Code with Markdown preview
  • Diagram Tools:
    • Mermaid (built-in support)
    • draw.io for complex diagrams
    • Excalidraw for sketches
  • Screenshot Tools: Include annotations
  • Linting: markdownlint

Helpful Extensions (VS Code)

{
  "recommendations": [
    "yzhang.markdown-all-in-one",
    "davidanson.vscode-markdownlint",
    "streetsidesoftware.code-spell-checker",
    "bierner.github-markdown-preview"
  ]
}

Community Guidelines

Be Respectful

  • Welcome newcomers
  • Provide constructive feedback
  • Acknowledge contributions
  • Respect different perspectives

Be Collaborative

  • Share knowledge freely
  • Help others contribute
  • Review PRs promptly
  • Improve based on feedback

Recognition

We value all contributions! Contributors are:

  • Listed in our Contributors file
  • Mentioned in release notes
  • Eligible for contributor badges

Questions?

If you have questions:

  • Check existing documentation
  • Ask in our Slack channel: #docs
  • Email: docs@tresor.vn
  • Open a Discussion

License

By contributing, you agree that your contributions will be licensed under the same license as the project.

Thank you for helping make our knowledge center better! 🎉

results matching ""

    No results matching ""