docs

CarbonLedger Documentation

Welcome to the CarbonLedger documentation! This directory contains all guides, references, and resources for contributors and users.

📚 Documentation Index

🚀 Getting Started

Perfect for new contributors:

Document	Description	Time
New Contributor Guide	Complete overview for first-time contributors	5 min read
Quick Start Guide	Fastest path from zero to running tests	15-25 min
Setup Checklist	Step-by-step verification checklist	10 min

📖 Detailed Guides

In-depth documentation:

Document	Description	Audience
Contributing Guide	Complete setup, workflow, and guidelines	All contributors
Troubleshooting Guide	Solutions to common issues	Everyone
Testnet Guide	Stellar testnet setup and usage	Developers

🏗️ Architecture

Understanding the system:

Document	Description	Audience
Architecture Decision Records	Why we made key technical decisions	Developers
Deployment Guide	Production deployment instructions	DevOps
TTL Cost Analysis	Soroban storage cost analysis	Developers
Verifier Onboarding	Guide for carbon verifiers	Verifiers

🌿 Carbon Domain References

Document	Description	Audience
Carbon Methodology Reference	Supported methodologies, scoring rubric, and contract parameter mapping	All contributors

🔌 API Documentation

Technical references:

Document	Description	Audience
Projects API	Backend API endpoints	Frontend devs
Error Code Reference	All 23 contract error codes with causes, resolutions, and frontend mapping	Frontend devs, integrators

---

🎯 Quick Navigation

I want to...

Start Contributing

1. Read New Contributor Guide
2. Follow Quick Start Guide
3. Use Setup Checklist to verify

Fix a Problem

1. Check Troubleshooting Guide
2. Search GitHub Issues
3. Ask in Discussions

Deploy to Testnet

1. Read Testnet Guide
2. Follow deployment steps
3. Test contract interactions

Understand Architecture

1. Read ADR Index
2. Review specific decisions
3. Check Main README

Deploy to Production

1. Read Deployment Guide
2. Review security checklist
3. Follow deployment steps

---

📋 Documentation Standards

File Naming

• Use SCREAMING_SNAKE_CASE.md for guides (e.g., QUICK_START.md)
• Use kebab-case.md for technical docs (e.g., deployment.md)
• Use ADR-NNN-title.md for architecture decisions

Structure

All guides should include:

• Clear title and description
• Table of contents (for long docs)
• Step-by-step instructions
• Code examples
• Troubleshooting section
• Links to related docs

Code Examples

# Always include comments
command --flag value  # Explain what this does

# Show expected output
# Output: Success message

Cross-References

Link to related documentation:

• Use relative paths: [Guide](GUIDE.md)
• Link to specific sections: [Section](GUIDE.md#section)
• Reference external docs: [Stellar Docs](https://developers.stellar.org)

---

🔄 Documentation Workflow

Adding New Documentation

1. Create the document:

   touch docs/NEW_GUIDE.md

2. Follow the template:

   • Title and description
   • Table of contents
   • Main content
   • Examples
   • Troubleshooting
   • Related links

3. Update this index:

   • Add to appropriate section
   • Include description
   • Specify audience

4. Link from other docs:

   • Update Main README
   • Update Contributing Guide
   • Cross-reference related docs

Updating Documentation

1. Keep it current:

   • Update when code changes
   • Verify commands still work
   • Check links aren't broken

2. Test instructions:

   • Follow your own guide
   • Verify on clean machine
   • Test on multiple platforms

3. Get feedback:

   • Ask for reviews
   • Watch for issues
   • Update based on questions

---

🎓 Learning Path

For New Contributors

1. Week 1: Setup

   • Read New Contributor Guide
   • Complete Quick Start
   • Run all tests successfully
   • Deploy to testnet

2. Week 2: Understanding

   • Read Architecture Decisions
   • Review smart contract code
   • Understand backend API
   • Explore frontend components

3. Week 3: Contributing

   • Pick a good first issue
   • Make your first PR
   • Get code reviewed
   • Iterate and merge

For Experienced Developers

1. Day 1: Setup

   • Quick setup (15-20 min)
   • Review architecture
   • Deploy to testnet

2. Day 2: Deep Dive

   • Read relevant ADRs
   • Review contract code
   • Test key features

3. Day 3: Contribute

   • Pick an issue
   • Submit PR
   • Engage with community

---

📊 Documentation Coverage

Guides Available

• ✅ New contributor onboarding
• ✅ Quick start (< 30 min)
• ✅ Detailed setup guide
• ✅ Troubleshooting reference
• ✅ Testnet setup
• ✅ Architecture decisions
• ✅ API documentation
• ✅ Deployment guide

Guides Needed

• ⏳ Security best practices
• ⏳ Performance optimization
• ⏳ Monitoring and observability
• ⏳ Backup and recovery
• ⏳ Upgrade procedures
• ⏳ Integration testing guide

Want to help? Pick a missing guide and create it!

---

🤝 Contributing to Documentation

Documentation contributions are highly valued!

What to Contribute

• Fix typos and grammar
• Add missing steps
• Improve clarity
• Add examples
• Update outdated info
• Create new guides

How to Contribute

1. Edit directly:

   git checkout -b docs/improve-quick-start
   # Edit docs/QUICK_START.md
   git commit -m "docs: clarify database setup steps"
   git push origin docs/improve-quick-start

2. Follow style guide:

   • Use clear, concise language
   • Include code examples
   • Add troubleshooting tips
   • Link to related docs

3. Test your changes:

   • Follow your own instructions
   • Verify on clean machine
   • Check all links work

---

🔍 Finding Information

Search Tips

1. Use GitHub search:

   • Search across all docs
   • Filter by file type
   • Search in code

2. Check the index:

   • This README
   • Main README
   • Contributing Guide

3. Browse by topic:

   • Setup: Quick Start, Contributing
   • Issues: Troubleshooting
   • Architecture: ADRs
   • Deployment: Deployment Guide

Still Can't Find It?

1. Search GitHub Issues
2. Ask in Discussions
3. Check Stellar Docs

---

📝 Documentation Checklist

Before submitting documentation:

• Spell-checked and grammar-checked
• Code examples tested
• Links verified
• Screenshots current (if any)
• Cross-references added
• Index updated
• Follows style guide
• Tested on clean machine

---

🎯 Documentation Goals

Objectives

1. Onboard new contributors in < 30 minutes
2. Reduce setup issues by 80%
3. Answer common questions proactively
4. Make architecture decisions transparent
5. Enable self-service troubleshooting

Metrics

• Time to first successful test run
• Number of setup-related issues
• Documentation feedback scores
• Contributor retention rate

---

🙏 Thank You

Thank you for reading and contributing to our documentation! Clear docs make the project accessible to everyone.

Questions? Ask in Discussions

Found an issue? Report it

Want to help? Pick a doc to improve and submit a PR!

---

Last Updated: 2024
Maintained By: CarbonLedger Contributors