Choose a Mermaid Gantt diagram when readers need task dates, durations, and dependencies. Choose a timeline when they need a sequence of events or milestones. Start with the question the document needs to answer before deciding how to draw it.
| Question | Useful starting point |
|---|---|
| When does each task start and finish? | Gantt |
| Which task follows another task? | Gantt |
| What happened during each release period? | Timeline |
| What are the main milestones in our story? | Timeline |
For a launch document, the delivery team may need a Gantt view while stakeholders need a timeline. Both can appear in the same Markdown file if their headings explain the difference in purpose.
This example assigns task IDs and uses after to express ordering. Mermaid's Gantt documentation describes date formats, durations, dependencies, and additional task features.
Give task names enough context for a reader who has not attended the planning meeting. “Review guide” is more useful than “Review” when the document also contains a code review or a legal review. Keep the chart short enough that readers can connect each task to the surrounding explanation.
Timeline entries use a period followed by event text. They are useful for a milestone narrative; do not infer task durations from the width or spacing of this diagram. See the Mermaid timeline reference for syntax and grouping options.
The dates here are illustrative. Replace them with your own milestones and keep the events in the order you want readers to follow. For a retrospective, use completed events. For a proposal, label the dates as planned so the chart does not imply commitments that have already been agreed.
A timeline becomes hard to scan if every small task becomes an event. A Gantt chart becomes difficult to use if its labels contain paragraphs of release history. Put the explanation in Markdown beneath the diagram and reserve diagram labels for the facts readers need to compare visually.
Try this editing test: ask someone what they learned from the diagram in ten seconds. If they can identify the release phases but cannot find the next deadline, a timeline may be doing its job while a schedule is still missing.
Keep each diagram in a fenced block marked mermaid. Open the Markdown in mdview.io and check the chart together with its heading and explanatory text. Use Markdown preview with Mermaid if you need a starting workflow.
Before sharing, verify the dates against your actual plan, remove obsolete tasks, and state who owns the schedule. A rendered diagram is only as useful as the information maintained in its source.