Standards & Guidelines
Humanet uses standardized formats and conventions to ensure ideas are clear, consistent, and easy to collaborate on.
Why Standards Matter
Standards provide:
- Consistency — Everyone knows what to expect
- Quality — Clear guidelines improve documentation
- Collaboration — Easier to work across different ideas
- Automation — AI can better understand and validate structured content
- Versioning — Track changes effectively with consistent formats
Core Standards
Documentation Standards
All text documentation uses Markdown format with specific conventions for structure and formatting.
Read Documentation Standards →
Key points:
- Use Markdown for all text documentation
- Follow consistent heading hierarchy
- Use templates for required files
- Include meaningful commit messages
Diagramming Standards
All visual diagrams use Draw.io (diagrams.net) for consistency, versioning, and ease of use.
Key points:
- Use Draw.io for all diagrams
- Save as
.drawiofiles for version control - Export to PNG/SVG for documentation
- Follow naming conventions and style guides
Tooling & Formats
Recommended Tools
| Purpose | Tool | Why |
|---|---|---|
| Diagrams | Draw.io | Free, web-based, version-controllable, extensive shape libraries |
| Documentation | Any Markdown editor | Markdown is universal and version-control friendly |
| Version Control | Git | Industry standard for tracking changes |
| Collaboration | Humanet Platform | Built-in threading, backlinking, and attribution |
File Formats
| Type | Format | Extension | Notes |
|---|---|---|---|
| Documentation | Markdown | .md | Plain text, version-controllable |
| Diagrams (source) | Draw.io XML | .drawio | Editable, can be tracked in Git |
| Diagrams (export) | PNG or SVG | .png, .svg | For embedding in documentation |
| Data | CSV, JSON | .csv, .json | Standard, parseable formats |
| Code | Language-specific | .js, .py, etc. | Use standard extensions |
Best Practices
For Documentation
- Write in clear, concise language
- Use consistent formatting
- Link to related documents
- Update docs when making changes
- Don’t use proprietary formats
- Don’t embed credentials or secrets
For Diagrams
- Use consistent colors and shapes
- Label all components clearly
- Include legends when needed
- Export in multiple formats
- Don’t create overly complex diagrams
- Don’t use screenshots instead of editable diagrams
For Organization
- Use meaningful file and folder names
- Keep related files together
- Add README to subdirectories
- Follow the repository structure conventions
- Don’t nest too deeply
- Don’t use spaces in file names (use hyphens or underscores)
Validation
The AI evaluator checks for compliance with standards:
- File formats — Correct extensions and formats
- Required files — All mandatory documentation present
- Naming conventions — Consistent, descriptive names
- Structure — Proper organization and hierarchy
- Completeness — No placeholder or empty files
Non-compliance doesn’t automatically fail validation, but it may result in suggestions for improvement.
Next Steps
- Diagramming Standards — Learn about Draw.io conventions
- Documentation Standards — Markdown and formatting guidelines
- Create Your First Idea — Put standards into practice
Last updated on