Package: markdown-plan
markdown-planmarkdown-planis a project planning syntax based on Markdown.# Example plan1.[x] This task is done2.The next task is bigger-With some sub-tasks-This task is unique-This one depends on @(unique)Writing your plan in Markdown offers some unique benefits:Tracking it in version controlPlotting progress over time to calculate better ETAsDocumenting changes to the planVisualizing a plan (e.g. as a DAG of tasks)Easily sharing a plan with othersAll of these things make planning more transparent and, hopefully, fun.ExamplesAburn-up chartmade from tracking a markdown plan in git:Vizualizing a markdown plan as aDAGof tasks:A Gantt chart generated from a markdown plan (bytopological ordering):SyntaxAny line formatted as a list item or header is a task.# Title task-child taskEverything else is ignored by default.-first task

This paragraph is ignored.-second task```A code block, also ignored.```Tasks can be organized into hierarchical lists, ordered or unordered.1.First-These two tasks...-Can happen in parallel2.Second (must happen after First)A task can be marked as "done" with a[x]at the beginning:- [x] my finished task
- [ ] todoTasks can also have explicit dependencies using the@(...)syntax, although this is rarely needed.-task1-task2-must be last @(task1, task2)Each dependency is a unique substring of the task it depends on.
The substring cannot include commas.ParsingAny valid plan can be parsed into atreeor aDAG, depending on the user's needs.It is possible to create cyclic dependencies using the dependency notation above.
A plan with cyclic dependencies is not a valid plan.ToolsThis repo ships with some basic CLI tools and a parsing library.Installpipinstallmarkdown-planUsage - command lineChanges to a plan can be tracked withgit, where each commit effectively links a version of the plan to its timestamp.
This history can be used to make projections about when the plan will finish, i.e. by plotting statistics over time.mdplanhistoryexample.plan.md# outputs jsonmdplanplotexample.plan.md# opens a plot (using that json data)Usage - libraryUsers are encouraged to create their own tools as they see fit.
The parsing library is designed to be easily extended.frommdplan.parseimportparse_tree# ... get the plan text ...tree=parse_tree(plan_text)# count the leavesnum_tasks=len(tree.leaves)# display the root task's descriptionroot_node=tree.roots.pop()task=root.valueprint(task.description)# ... see the Tree, Node, and Task classes for detailsfrommdplan.gitimportGitHistory# ... get the path to a plan ...history=GitHistory(path)# a history is just a chronological list of versiondates=[version.datetimeforversioninhistory]trees=[version.treeforversioninhistory]statistics=[version.task_statisticsforversioninhistory]# ... see the GitVersion class for more detailsUsed bymarkdown-plan-viewerMotivationThe main goal is to make planning easier and more useful.
Ultimately, planning should help us answer questions like:"When will this be done?""How are we doing so far?""What actually happened?"Good plans should be:easy to createeasy to adapteasy to sharePlans that are hard to read or write are difficult to share.Plans that are easy to edit encourage adapting to change.
Editing is easier if the history of edits is never lost, and each edit can be documented.If a plan is easy to parse, people are encouraged to build their own tools to help interpret the plan.AcknowledgementsThis project was inspired by Thomas Figg's "Programming is Terrible," Andrew Steel'sganttrepo, Dave Farley's video "How to Estimate Software Development Time," and Allen Holub's talk "No Estimates" (itself inspired by the book byVasco Duarte).