Dynamic Telemetry is a PROPOSAL : please provide feedback! :-)

Dynamic Telemetry is not an implementation, it's a request for collaboration, that will lead to an shared understanding, and hopefully one or more implementations.

Your feedback and suggestions on this document are highly encouraged!

Please:

Join us, by providing comments or feedback, in our Discussions page
Submit a PR with changes to this file ( docs/ReviewProcess.document.md)

Direct Sharing URL

http://microsoft.github.io/DynamicTelemetry/docs/ReviewProcess.document/

Review Process

Review Process Overview

The Dynamic Telemetry project involves multiple stakeholders, complex technical concepts, and evolving requirements that demand a systematic approach to documentation review and approval. This document establishes a comprehensive review process designed to ensure quality, consistency, and stakeholder alignment throughout the documentation lifecycle.

Given the complexity of dynamic telemetry systems and the diverse audience (developers, operators, architects, product managers, and end users), a structured review process is essential to prevent miscommunication, reduce technical debt, and maintain documentation quality standards.

Purpose and Benefits of the Review Process

Why Review Stages Are Necessary

The multi-stage review process serves several critical purposes:

Quality Assurance: Each stage acts as a quality gate, ensuring that documents meet specific criteria before advancing to the next level. This prevents low-quality or incomplete information from being disseminated to stakeholders.
Stakeholder Alignment: Different review levels accommodate different stakeholder needs. Early stages allow for rapid iteration among technical contributors, while later stages involve broader stakeholder review and formal sign-off.
Risk Mitigation: By establishing clear gates for forward progress, we reduce the risk of implementing features or processes based on incomplete or inaccurate documentation.
Resource Optimization: The staged approach allows teams to invest appropriate levels of effort at each phase, avoiding over-engineering early drafts while ensuring thorough review of finalized documents.
Change Management: Clear status indicators help teams understand when documents are stable enough to base decisions upon, and when they should expect continued evolution.

Reducing Confusion Through Clear Status

Each document includes a standardized header that immediately communicates its review status:

author: <name of the primary author>
status: <one of the review levels defined below>

This approach ensures that readers immediately understand:

Who is responsible for the document's content
What level of review and validation the document has received
Whether the document is appropriate for their current decision-making needs
What level of feedback is appropriate at the current stage

Detailed Review Stages

The review process consists of six distinct stages, each with specific entry criteria, deliverables, and exit gates:

ReviewLevel1 (Incomplete)

Purpose: Placeholder stage for documents that are planned but not yet started or are in very early development.

Entry Criteria:

Document concept has been identified and approved for development
Primary author has been assigned
Document structure or outline may exist

Requirements:

Should include basic metadata (author, intended audience, scope)
May contain high-level outline or table of contents

Exit Gate:

Document contains substantial talking points or initial content
Author is ready to begin detailed writing

Stakeholder Involvement: Primary author only

Typical Duration: 1-2 weeks for planning and initial scoping

ReviewLevel1b (Talking Points)

Purpose: Establishes the foundation and scope of the document through structured talking points.

Entry Criteria:

Meets all ReviewLevel1 requirements
Author has developed clear understanding of document scope and objectives

Requirements:

All major sections identified with talking points enumerated
Key concepts, terminology, and scope clearly defined
Target audience and use cases specified

Exit Gate:

Talking points provide sufficient detail for full document development
Section structure is logical and comprehensive
Primary stakeholders have reviewed and approved the approach

Stakeholder Involvement: Primary author, technical leads, immediate team members

Typical Duration: 1-2 weeks for talking point development and initial review

ReviewLevel2 (PRE-DRAFT)

Purpose: Full content development phase where the document is being actively written but not yet ready for broader feedback.

Entry Criteria:

Meets all ReviewLevel1b requirements
Talking points have been approved by immediate stakeholders

Requirements:

All sections contain substantial content beyond talking points
Technical accuracy verified by author and immediate team
Internal consistency maintained throughout document
All placeholder content replaced with actual information

Exit Gate:

Document is complete enough to provide value to readers
Author believes content is technically accurate and ready for review
All major sections are substantively complete

Stakeholder Involvement: Primary author, subject matter experts, immediate technical team

Typical Duration: 2-4 weeks depending on document complexity

ReviewLevel3 (DRAFT)

Purpose: Collaborative review phase where the document is stable enough for broader stakeholder feedback.

Entry Criteria:

Meets all ReviewLevel2 requirements
Document provides comprehensive coverage of its stated scope

Requirements:

Content is complete and technically accurate
Writing is clear and appropriate for target audience
All references, links, and citations are valid
Document structure supports its intended use cases

Exit Gate:

All review feedback has been addressed or explicitly deferred
No major gaps or inaccuracies remain
Document serves its intended purpose effectively

Stakeholder Involvement: Extended team, cross-functional reviewers, potential end users

Typical Duration: 2-3 weeks for review cycles and revision

ReviewLevel4 (PENDING)

Purpose: Final validation phase where the document is functionally complete and undergoing final approval processes.

Entry Criteria:

Meets all ReviewLevel3 requirements
All substantial feedback from draft review has been incorporated

Requirements:

Document is considered "feature complete" for its intended scope
All stakeholder concerns have been addressed
Content is ready for operational use
Change control process is in effect (changes require justification)

Exit Gate:

Formal sign-off from all required stakeholders
Document meets all quality and completeness criteria
No blocking issues remain unresolved

Stakeholder Involvement: All stakeholders, formal reviewers, decision makers

Typical Duration: 1-2 weeks for final review and sign-off

ReviewLevel5 (COMPLETE)

Purpose: Fully approved and locked documentation that serves as authoritative reference.

Entry Criteria:

Meets all ReviewLevel4 requirements
Formal approval received from all required stakeholders

Requirements:

Document is considered authoritative for its domain
All stakeholders have formally approved the content
Document is suitable for external distribution (if applicable)
Version control and change management processes are established

Change Management:

Changes require formal change request process
Modifications are tracked as errata or versioned updates
Impact assessment required for any substantive changes

Stakeholder Involvement: Document owner for maintenance, formal change control board for modifications

Maintenance: Ongoing maintenance as needed, formal review cycles as defined by document type

Implementation Guidelines

For Authors

Starting a New Document:

Begin at ReviewLevel1 with clear scope and author assignment
Develop comprehensive talking points before advancing to ReviewLevel1b
Ensure each stage's exit criteria are met before progression
Actively seek appropriate stakeholder input at each level

Managing Document Progression:

Update status headers promptly when advancing between levels
Maintain clear change logs during draft and review phases
Communicate timeline expectations to stakeholders
Address feedback systematically and document resolutions

For Reviewers

Review Responsibilities by Level:

ReviewLevel1-2: Focus on scope, approach, and technical accuracy
ReviewLevel3: Provide comprehensive feedback on content, clarity, and completeness
ReviewLevel4: Final validation and formal approval
ReviewLevel5: Ongoing maintenance review as needed

Effective Review Practices:

Provide specific, actionable feedback
Consider the document's intended audience and use cases
Distinguish between blocking issues and suggestions for improvement
Respond within established timeframes for each review level

For Stakeholders

Engagement Guidelines:

Understand which review levels require your input
Provide timely feedback during appropriate review windows
Distinguish between draft feedback and final approval
Respect the change control process for completed documents

Quality Gates and Forward Progress Criteria

Gate Criteria Matrix

Each transition between review levels requires meeting specific criteria:

From Level	To Level	Required Criteria
-	ReviewLevel1	Document concept approved, author assigned
ReviewLevel1	ReviewLevel1b	Talking points/scope defined
ReviewLevel1b	ReviewLevel2	All sections have substantial content
ReviewLevel2	ReviewLevel3	Content complete, ready for feedback
ReviewLevel3	ReviewLevel4	Feedback addressed+stakeholder review complete
ReviewLevel4	ReviewLevel5	Final sign-off, no blocking issues

Status of (Current) Documents

Individual Status

author: Generated File status: Level5

Level1

File	Word Count
../docs/Applications.InterestingApplications.document.md	10
../docs/Persona_DataAnalysis.document.md	122
../docs/PositionPaper.TestingWithEntropy.document.md	14
../docs/Persona_DevOps.document.md	110
../docs/GeneratedFileStatus.md	7
../docs/Architecture.Probe.user_events.document.md	13
../docs/Architecture.Processor.External.OffBox.document.md	97
../docs/Persona_ProjectManager.document.md	121
../docs/Architecture.Action.FileCollection.document.md	13
../docs/Architecture.Probe.DTrace.document.md	18
../docs/PositionPaper.ScarcityAndHumans.md	15
../docs/Architecture.Probe.ptrace.document.md	13
../docs/PositionPaper.TriggeredFlightRecorder.document.md	13
../docs/Architecture.DesignPatterns.Valves.document.md	10
../docs/PositionPaper.ConvertLogsToMetrics.document.md	17
../docs/Architecture.Action.StateCollection.document.md	13
../docs/PositionPaper.SelfDescribingProductionCode.document.md	19
../docs/Architecture.Probe.eBPF.document.md	13
../docs/PositionPaper.AuditingProductionCode.document.md	20
../docs/PositionPaper.DefiningProduction.document.md	27
../docs/Architecture.Action.CallstackWalk.document.md	14
../docs/PositionPaper.ProbeRiskLevels.document.md	61
../docs/PlaceHolder.document.md	18
../docs/Ideas.ToExpandOn.document.md	146
../docs/PositionPaper.TriggeredCollections.document.md	13
../docs/Architecture.DesignPatterns.Toggles.document.md	10
../docs/Architecture.Probe.OpenTelemetry.document.md	13
../docs/Architecture.Action.ProcessExecution.document.md	13
../docs/Architecture.FlightRecorder.CubbyHole.document.md	15
../docs/Architecture.Probe.Breakpoint.document.md	103
../docs/Architecture.Action.CPUSample.document.md	13
../docs/Architecture.Action.VerboseLogs.document.md	13
../docs/Architecture.Processor.External.OnBox.document.md	85
../docs/Architecture.Action.MemoryDump.document.md	10
../docs/Scenarios.EventFieldSuppression.document.md	16
../docs/PositionPaper.Actions.document.md	13
../docs/Applications.Overview.InterestingApplications.document.md	7
../docs/PositionPaper.ABTestingWithRichDiagnostics.document.md	14
../docs/Architecture.Probe.ETW.document.md	13
../docs/Scenarios.EventSuppression.document.md	15
../docs/Scenarios.ConvertLogsToMetrics.document.md	15
../docs/Demos.0.DurableID.md	618
../docs/Scenarios.ExtractingMemoryWithUProbe.document.md	15
../docs/PositionPaper.ProceduralizeNets.document.md	16
../docs/PositionPaper.GuideToLogVerbosity.document.md	17
../docs/Architecture.Probe.uprobes.document.md	13
../docs/Architecture.DesignPatterns.Counters.document.md	10
../docs/PositionPaper.DynamicallyToggleLogs.document.md	13
../docs/Definitions.document.md	19
../docs/Architecture.Components.FileBased.Observability.document.md	10
../docs/Architecture.Action.PacketCapture.document.md	14
../docs/PositionPaper.TraditionalTesting.md	15
../docs/Scenarios.EventAggregation.document.md	15
../docs/Slides.Overview.Presentation.md	377
../docs/PositionPaper.ConfigurationDeployment.document.md	71
../docs/Architecture.DesignPatterns.DesignPatterns.Overview.document.md	14
../docs/Scenarios.ChangingEnvironments.document.md	15
../docs/Architecture.DesignPatterns.Queues.document.md	10
../docs/Architecture.DesignPatterns.Triggers.document.md	10
../docs/PositionPaper.ClearFailuresViaSchema.document.md	16
../docs/Architecture.Action.FlightRecorder.document.md	33
../docs/PositionPaper.ProbeToHeader.document.md	15
../docs/PositionPaper.PositionPapers.Overview.document.md	13
../docs/Architecture.Processor.Installation.Overview.document.md	46
../docs/Persona_Developer.document.md	153
../docs/Architecture.Action.ConfigCollection.document.md	13
../docs/PositionPaper.FlightRecorder.document.md	17

Level2

File	Word Count
../docs/Scenarios.Overview.DeepDiagnostics.document.md	760
../docs/Demos.1.DropChattyLog.md	1103
../docs/Architecture.Components.FiltersAndRouters.document.md	922
../docs/Architecture.KeyConstructs.Overview.document.md	933
../docs/Demos.HighLevel.Overview.md	1187
../docs/Architecture.Processor.Kernel.document.md	849
../docs/Personas.Overview.document.md	257
../docs/Architecture.Processor.Language.md	476
../docs/PositionPaper.ThinkLike.RTOS.document.md	43
../docs/Architecture.Processor.StateMachine.document.md	472
../docs/Architecture.Probes.Overview.document.md	1395
../docs/index.md	455
../docs/PositionPaper.DurableIds_StructuredPayloads.document.md	1242
../docs/Demos.4.AddTelemetryDemo.md	1084
../docs/Architecture.FlightRecorder.Overview.document.md	902
../docs/Rude_Q_and_A.md	1131
../docs/Architecture.Processor.Overview.document.md	949
../docs/Scenarios.Overview.Reliability.document.md	2218
../docs/PositionPaper.ObserverEffect.document.md	728
../docs/Architecture.FlightRecorder.ShortHorizons.document.md	633
../docs/Scenarios.Overview.RedactingSecrets.document.md	1093
../docs/Architecture.FlightRecorder.LongHorizons.document.md	795
../docs/Architecture.Processor.QueryLanguage.document.md	349
../docs/Scenarios.Overview.DurableDashboards.Alerts.document.md	571
../docs/Scenarios.Overview.CostReduction.document.md	1391

Level1b

File	Word Count
../docs/Architecture.FlightRecorder.TraceHorizons.document.md	466
../docs/PositionPaper.TelemetryUmbilical.document.md	92
../docs/HowTo.UseThisDocumentation.document.md	332
../docs/PositionPaper.SharingDataAmongStakeHoldersIsHard.document.md	180
../docs/Architecture.Actions.Overview.document.md	124
../docs/Architecture.Components.Streaming.Observability.document.md	59
../docs/PositionPaper.FileAndStreaming.document.md	224
../docs/Scenarios.Overview.document.md	180
../docs/Applications.FlightRecorder.MemoryLeak.document.md	211
../docs/PositionPaper.DeliveryGuarantees.document.md	163
../docs/Applications.FlightRecorder.PriorToCrash.document.md	252
../docs/Architecture.Processor.InProcess.document.md	53
../docs/Architecture.Overview.document.md	333
../docs/Demos.2_DynamicProbe.md	277

Level3

File	Word Count
../docs/ReviewProcess.document.md	1402

Change Management for This Document

This ReviewProcess.document.md itself follows the review process it defines. Changes to the review process require:

Minor Updates (clarifications, typos): Direct edit with notification to document users
Process Improvements (new criteria, modified gates): ReviewLevel3 process with stakeholder review
Major Changes (new review levels, fundamental process changes): Full ReviewLevel1-5 process with formal approval

For questions about this review process or suggestions for improvement, contact the document author or raise issues through the established feedback channels.