220 lines
6.0 KiB
Plaintext
220 lines
6.0 KiB
Plaintext
---
|
|
title: How We Communicate
|
|
description: Building a global AI platform requires clear, open communication
|
|
---
|
|
|
|
We're a fully-remote team building open superintelligence across continents
|
|
and cultures. Clear communication isn't just nice to have—it's how we ship fast,
|
|
stay aligned, and build trust with millions of users.
|
|
|
|
## Core Communication Principles
|
|
|
|
### Default to Open
|
|
|
|
- **Build in Public**: Development discussions happen in open GitHub issues
|
|
- **Share Progress**: Daily updates in Discord keep everyone informed
|
|
- **Document Decisions**: Important choices are recorded for future reference
|
|
- **Learn Together**: Share discoveries, failures, and insights with the team
|
|
|
|
### Async First, Sync When Needed
|
|
|
|
As a global team, we optimize for asynchronous communication:
|
|
|
|
- **GitHub**: Technical discussions, code reviews, feature planning
|
|
- **Discord**: Quick questions, daily updates, community engagement
|
|
- **Documentation**: Long-form thinking, architectural decisions
|
|
- **Meetings**: Only when real-time collaboration adds value
|
|
|
|
### Write for Clarity
|
|
|
|
With team members from different linguistic backgrounds:
|
|
|
|
- **Simple English**: Clear over clever, direct over diplomatic
|
|
- **Context Included**: Assume readers lack your specific context
|
|
- **Examples Help**: Show, don't just tell
|
|
- **Visual Aids**: Diagrams, screenshots, and code samples
|
|
|
|
> Good: "The model fails to load on M1 Macs. Here's the error log and steps to reproduce..."
|
|
> Bad: "It's broken on Mac."
|
|
|
|
## Communication Channels
|
|
|
|
### Where to Communicate What
|
|
|
|
| Type | Channel | Examples |
|
|
|------|---------|----------|
|
|
| **Feature Development** | GitHub Issues | New features, bug reports, technical discussions |
|
|
| **Daily Updates** | Discord #daily-updates | What you worked on, blockers, discoveries |
|
|
| **Quick Questions** | Discord team channels | "Anyone know why X happens?" |
|
|
| **Long-form Thinking** | GitHub Discussions / Docs | Architecture proposals, post-mortems |
|
|
| **User Support** | Discord #support | Helping users with Jan |
|
|
| **Urgent Issues** | Discord + @mention | Production bugs, security issues |
|
|
|
|
### Response Time Expectations
|
|
|
|
- **GitHub Issues**: Within 24-48 hours
|
|
- **Discord Questions**: Best effort, timezone dependent
|
|
- **User Bug Reports**: Acknowledge within 24 hours
|
|
- **Security Issues**: Immediate escalation
|
|
|
|
## Communication Best Practices
|
|
|
|
### For Engineers
|
|
|
|
```
|
|
✅ DO:
|
|
- Comment your code like someone will read it at 3am
|
|
- Update documentation when you change behavior
|
|
- Share WIP early for feedback
|
|
- Close the loop: report back on solutions
|
|
|
|
❌ DON'T:
|
|
- Assume context that isn't written down
|
|
- DM technical discussions (keep them public)
|
|
- Wait until perfect to share progress
|
|
- Leave PRs without description
|
|
```
|
|
|
|
### For Everyone
|
|
|
|
**Assume Positive Intent**
|
|
- We're all working toward the same goal
|
|
- Language barriers can cause misunderstandings
|
|
- Ask for clarification before assuming
|
|
|
|
**Be Specific**
|
|
- "The download button doesn't work" → "The download button on Windows returns 404 for model X"
|
|
- "It's slow" → "Model loading takes 45 seconds on 8GB RAM"
|
|
- "Users want this" → "15 users requested this in issue #123"
|
|
|
|
**Close Loops**
|
|
- Follow up on questions you ask
|
|
- Update issues with solutions
|
|
- Thank people who help you
|
|
- Share outcomes of discussions
|
|
|
|
## Meetings That Work
|
|
|
|
We minimize meetings but when we have them:
|
|
|
|
### Before the Meeting
|
|
- Share agenda 24 hours prior
|
|
- Include pre-read materials
|
|
- State desired outcome clearly
|
|
- Invite only necessary people
|
|
|
|
### During the Meeting
|
|
- Start with 5-minute silent reading of materials
|
|
- Stick to agenda
|
|
- Assign action items with owners
|
|
- End 5 minutes early
|
|
|
|
### After the Meeting
|
|
- Post summary in relevant channel
|
|
- Create GitHub issues for action items
|
|
- Share recording if applicable
|
|
|
|
## Writing Culture
|
|
|
|
### Pull Requests
|
|
|
|
```markdown
|
|
## What
|
|
Brief description of changes
|
|
|
|
## Why
|
|
Context and motivation
|
|
|
|
## How
|
|
Technical approach
|
|
|
|
## Testing
|
|
How to verify it works
|
|
|
|
## Screenshots
|
|
If UI changes
|
|
```
|
|
|
|
### Daily Updates
|
|
|
|
Keep them brief but informative:
|
|
|
|
```
|
|
**Yesterday**: Shipped GGUF loader optimization (30% faster)
|
|
**Today**: Working on Windows installer bug #456
|
|
**Blockers**: Need review on PR #789
|
|
**TIL**: Quantization affects different models differently
|
|
```
|
|
|
|
### Documentation
|
|
|
|
- Write docs as you code
|
|
- Include examples users can copy
|
|
- Explain the why, not just the how
|
|
- Keep it up to date or delete it
|
|
|
|
## Community Communication
|
|
|
|
When engaging with our open-source community:
|
|
|
|
### Be Helpful
|
|
- No question is too basic
|
|
- Provide context and examples
|
|
- Point to relevant documentation
|
|
- Follow up on issues
|
|
|
|
### Be Humble
|
|
- We don't have all the answers
|
|
- Users often have great ideas
|
|
- Mistakes happen, own them
|
|
- Thank contributors publicly
|
|
|
|
### Be Human
|
|
- Personality is welcome
|
|
- Celebrate wins together
|
|
- Share the journey
|
|
- Build relationships
|
|
|
|
## Global Team Considerations
|
|
|
|
### Time Zones
|
|
- Post updates at consistent times
|
|
- Record important discussions
|
|
- Rotate meeting times fairly
|
|
- Respect off hours
|
|
|
|
### Cultural Awareness
|
|
- Direct feedback styles vary by culture
|
|
- Silence doesn't mean agreement
|
|
- Ask if unsure about interpretation
|
|
- Celebrate diverse perspectives
|
|
|
|
### Language
|
|
- English is second language for many
|
|
- Avoid idioms and slang
|
|
- Use simple, clear language
|
|
- Be patient with communication
|
|
|
|
## Red Flags to Avoid
|
|
|
|
- **Information Hoarding**: Share knowledge freely
|
|
- **Private Discussions**: Keep technical talk public
|
|
- **Assuming Context**: Document everything
|
|
- **Delayed Responses**: Acknowledge even if you can't solve immediately
|
|
- **Unclear Communication**: If confused, ask for clarification
|
|
|
|
## The Jan Way
|
|
|
|
Our communication style reflects our values:
|
|
- **Open**: Like our code
|
|
- **Inclusive**: Like our community
|
|
- **Clear**: Like our mission
|
|
- **Async**: Like our architecture
|
|
- **Global**: Like our vision
|
|
|
|
Good communication at Jan isn't about perfection—it's about clarity, openness, and building together across any distance.
|
|
|
|
---
|
|
|
|
*"The best code is documented code. The best decisions are documented decisions. The best team is one that communicates openly."*
|