Document Standardization Meeting Minutes

Meeting Info ¶

Meeting Detailed Agenda ¶

Where to put document ¶

Below are some aspects that we should take into concern.

Different Type Comparation ¶

Doc Category ¶

1. API Doc, e.g. # Cluster Status API and Server Detail Status API
2. Design Doc, e.g. # Design for global service account support in MCT
3. Knowledge Base
   1. Platform Info, e.g. # All servers type in MCT
   2. Knowledge Sharing, # Getting Started with CI
4. Feature Guide / Introduction
   1. Plugin Logic, e.g. # MCT Monitoring TSP Logic
   2. Runbook, # MCT Operational Runbook
   3. MCT User Guide
5. Milestone (sub project), e.g. # MCT Global Agent (Project code: Hydra)
6. Recording
   1. Issue Recording, # MCT Production or BTS issue analysis
   2. Process Recording (temp), e.g. # service migration and monitoring support task
   3. Release Note, e.g. # MCT15.4.0 release

End User ¶

• Internal engineer
• 3-rd engineer
• Customer

Organizate document (how to find document) ¶

• Tag cloud
• Strucutred wiki
  • High Cohesion and Well-Categorized
  • Appropriately flatten
• Global Search
• make good use of README.md

is it necessary to add a unified doc protal for whole Monitoring & Alerting team?

How to write document (guideline) ¶

• Doc heading with background, what, why, how... Principle: simple and concise
• Doc Review / Vote / Acceptance test
• Unified content format / style to make our wiki more profisional, some reference: > Apache Dubbo

  Markdown 书写风格指南

How to keep document valid ¶

• Make Documentation as part of development process
• Evaluate doc effort on planing meeting
• Make Doc more close to project
• Acceptance test for Doc?
• Remove All invalid (useless) docs

How to implement ¶

WE set rule, each team execute (team member act as a connector)

Meeting Minutes / Action Items: ¶

outputs of the meeting lists as below.

About This Meeting: ¶

• Extend meeting time range according to meeting content (or adjust meeting topic)
• Post discussion content Early, leave time for members to be prepared
• Split Time Block: Background Introduction (10mins) / Discussion (10mins) / Vote & Conclusion (10mins)
• More focused Topic

About Wiki: ¶

Closed Topics: ¶

• Maintain two types of wiki will be enough: - Internal + 3-rd party wiki: focus on code level more detailed logic - Customer wiki: fresh user level usage guide
• How to implement our guideline: - Our Virtual Team set rule, each service team follow our rule - Virtual Team Member* should act as a connector and push the process on daily Agile run.

Open Topics: ¶

• Where to put document - aggrement here is, readme.md is important, and there should be Search function - Where to place OUR document, Customer wiki, and developer wiki - Rich text or markdown
• How to organizate wiki - structured wiki design
• How to write document - Document template? - Unified wiki style?
• How to keep document valid