Documentation Guidelines
Concrete protocol internal documentation
Creating Effective Technical Documentation: A Step-by-Step Guide
Goal: When new team members join, our documentation should seamlessly integrate into their onboarding process, helping them grasp our project quickly. Our documentation should also empower everyone to discuss our project in a cocktail sense confidently. These documents will ensure everyone on the team has a clear understanding of how and why it was built and where it fits. Consider the following when creating your documentation:
Clarity and Simplicity: Use straightforward language, concise paragraphs, and bullet points for easy comprehension.
Visual Aids: Enhance understanding by incorporating diagrams, flowcharts, sequence diagrams, and screenshots when needed.
Code Illustrations: Include pertinent code snippets with explanations, showcasing API usage, libraries, or features.
Stay Current: As software evolves, your documentation should as well. Continuously update it to mirror advancements and enhancements in the software.
Document Outline
Introduction: Brief Introduction and Software Objectives
System Architecture: Overview of High-Level System Structure and Components
Common Gotchas and Key Concepts: essential concepts that the team should be aware of when interacting with the build.
Integration within the Product Ecosystem: How and Where?
User Guide: Guidelines on How to Effectively Use the Software, Including Typical Scenarios
API Reference: Comprehensive Documentation for APIs, if Applicable
References: All docs related to the product that has been used or referred.
Review
Team Review: Once the document is complete, share it with the team inside the concrete-core-docs channel.
Feedback and Suggestions: The team review should provide feedback on the document's clarity, accuracy, and completeness. Suggestions for improvements should be communicated constructively.
Content Alignment: Ensure that the document aligns with the Document Outline, addressing the key sections and objectives.
Incorporate Feedback & Approval: Incorporate the feedback collected during the review process into the document, and then submit it for a final review.
Last updated