{"id":17464431,"url":"https://github.com/brainlid/wbs_markdown","last_synced_at":"2025-04-19T18:25:03.550Z","repository":{"id":65379261,"uuid":"104746714","full_name":"brainlid/wbs_markdown","owner":"brainlid","description":"Generate a Work Breakdown Structure (WBS) report from a markdown file. A tool that improves software development estimates.","archived":false,"fork":false,"pushed_at":"2019-12-07T15:34:58.000Z","size":193,"stargazers_count":50,"open_issues_count":4,"forks_count":10,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-08T20:47:06.639Z","etag":null,"topics":["breakdown","breakdown-structure","confidence","estimate","html-report","markdown","software-estimation","story","wbs","wbs-markdown"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brainlid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-25T12:24:58.000Z","updated_at":"2025-04-03T19:46:41.000Z","dependencies_parsed_at":"2023-01-20T08:45:48.054Z","dependency_job_id":null,"html_url":"https://github.com/brainlid/wbs_markdown","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainlid%2Fwbs_markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainlid%2Fwbs_markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainlid%2Fwbs_markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainlid%2Fwbs_markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brainlid","download_url":"https://codeload.github.com/brainlid/wbs_markdown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249762410,"owners_count":21321930,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["breakdown","breakdown-structure","confidence","estimate","html-report","markdown","software-estimation","story","wbs","wbs-markdown"],"created_at":"2024-10-18T10:45:44.343Z","updated_at":"2025-04-19T18:25:03.530Z","avatar_url":"https://github.com/brainlid.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WBS Markdown\n\nWBS Markdown is an NPM package designed to make it easier for software\ndevelopers to create and manage a [Work Breakdown Structure\n(WBS)](https://en.wikipedia.org/wiki/Work_breakdown_structure). A WBS can be a\npowerful tool in the estimation process. This is fully compatible with an Agile\nworkflow.\n\n## Purpose\n\nThis tool is designed to be used by a software developer and assumes you are\nskilled at editing text files (markdown specifically). The breakdown structure\nis managed in a [Markdown file](https://en.wikipedia.org/wiki/Markdown) format\nwhich you are probably already familiar with. Using your favorite editor you can\ncollapse regions, perform mass updates, re-structure, and more.\n\nThe generated report is a static HTML file. It uses [Vue.js](https://vuejs.org/)\ncomponents to add some interactive features.\n\n## Examples\n\nExample reports that show different ways of using the WBS Markdown tool. These\nare the rendered static HTML reports that are created from a markdown file.\n\n- [Bicycle Product Sample](https://brainlid.org/assets/static-html/wbs-markdown/wbs.bicycle-product.html) - [Markdown file](./examples/wbs.bicycle-product.md) Example shows the breakdown of a the creation of a new bicycle product. This is an adaptation from an example given on the [WBS Wikipedia page](https://en.wikipedia.org/wiki/Work_breakdown_structure#Example).\n- [Rails Commerce Project](https://brainlid.org/assets/static-html/wbs-markdown/wbs.rails-commerce.html) - [Markdown file](./examples/wbs.rails-commerce.md) Example shows a simple/small Rails e-Commerce project with a detailed breakdown of a new \"Forgot my password\" feature. This is a \"high level of detail\" breakdown and is an example of what that may look like. Remember, you choose the appropriate Level of Detail for your immediate need.\n\n## Background\n\nHow many times have you estimated a new feature and you ended up being *way*\noff? Yeah, I've been there too many times myself. Management and Project\nManagers need *some* idea of the amount of work something will be. This helps me\ngive a better estimate so I don't forget parts of the system that are impacted\nby a change.\n\nAs we continue to build out the features and the product, the project file is\nchecked in with our source code so it is shared and expanded to represent the\ncode being created.\n\nAn additional benefit, I wanted to be able to track the progress of features\nbeing built. This allows for marking off tasks as being completed (which can be\nchecked in with the implementing code). Since the report output is a static HTML\nfile, a project build system can generate the report for what is committed on,\nsay, the master branch and expose feature progress in that way as well.\n\nI created this tool for myself and my team. I share it in the hopes it can help\nothers as well.\n\n## Installation\n\nUsing `npm`:\n\n```\nnpm install -g wbs-markdown\n```\n\nUsing `yarn`: (NOTE: Installation using yarn currently doesn't work and is a [known issue](https://github.com/brainlid/wbs_markdown/issues/19). The workaround for now is to install using npm.)\n\n```\nyarn global add wbs-markdown\n```\n\nUpgrading to a newer version:\n\n```\nyarn global upgrade wbs-markdown\n```\n\n## Getting Started\n\n### Quick Start\n\nThese are the commands use:\n\n- `wbsm init` - One-time setup for a directory. Creates a configuration file.\n- `wbsm new` - Creates a new `wbs.project.md` markdown file.\n- `wbsm r` - Generates an HTML report from the default `wbs.project.md` file.\n- `wbsm w` - Watch for changes to the `wbs.project.md` file and auto-generate the HTML report.\n- `wbsm o` - Open the generated report in your default browser.\n\n### Initialize a new project configuration\n\n```\nwbsm init\n```\n\nThis will create a file named `.wbsm-config.json` in your current working\ndirectory.\n\nThis is a sample configuration file:\n\n```json\n{\n  \"reportTitle\": \"WBSM Project Report\",\n  \"defaultWorkUnit\": \"d\",\n  \"unitConversion\": {\n    \"h\": 1,\n    \"d\": 6,\n    \"w\": 30,\n    \"m\": 120\n  },\n  \"avgHoursPerDay\": 4.5,\n  \"workUnitConfidencePct\": {\n    \"h\": 95,\n    \"d\": 80,\n    \"w\": 60,\n    \"m\": 30\n  }\n}\n```\n\n### Create New Markdown Project File\n\nCreate a new project markdown file. This file can be checked in with the\nsourcecode of your project.\n\n```\nwbsm new\n```\n\nOptionally specify the name of the new file to create. Defaults to\n`wbs.project.md`.\n\n```\nwbsm new wbs.my-project.md\n```\n\nThis is helpful for generating the report explicitly when you want. For instance,\na CI server could generate the report file based on a git hook commit to master.\n\n### Generate a Report\n\nBasic version. Defaults to look for a markdown file titled `wbs.project.md`.\n\n```\nwbsm report\nwbsm r\n```\n\nYou can generate a report from a specifically named file using the `-m` flag and\nthe filename.\n\n```\nwbsm report -m wbs.my-project.md\nwbsm r -m wbs.my-project.md\n```\n\nYou can override the generated HTML report output filename using the `-r` flag\nand the filename.\n\n```\nwbsm report -r custom-report-name.html\nwbsm r -r custom-report-name.html\n```\n\nAfter generating the report, open it in the default system browser using the `-o` flag.\n\n```\nwbsm report --open\nwbsm r -o\n```\n\n### Watch for Changes and Auto-Generate Report\n\nBasic version. Defaults to look for a markdown file titled `wbs.project.md`.\n\n```\nwbsm watch\nwbsm w\n```\n\nThis uses the same command options as `wbsm report`. You can override the\nmarkdown file to use and the output file to generate.\n\nThis is helpful when you are working on your project file and keep switching\nback to the report.\n\n### Get CLI Help\n\n```\nwbsm --help\nwbsm new --help\nwbsm report --help\nwbsm watch --help\nwbsm open --help\n```\n\n## Upgrade Notes\n\nIf upgrading from a pre-1.0 version, you will want to add the \"filter\" component\nto your project file. This became a component which lets you customize the\ndefault display mode and the placement of the filter selection in your report.\n\n## Usage\n\nThe document uses a Markdown style. Anything you can create in Markdown is\nvalid. This makes it easy to customize and create something that works and makes\nsense for your project and organization.\n\n### Components\n\nThere are a number of \"components\" to use for helping to get the most out of\nbuilding a Work Breakdown Structure in Markdown.\n\n#### Story Item\n\nThere are several valid ways to define a story item.\n\n```markdown\n- Story description {story=StoryId}\n- **StoryId**: Story description {story=StoryId}\n- **StoryId**: Story description {story=StoryId group=\"Group Name\"}\n```\n\nThe first one is minimum for a Story. A story can optionally be linked to a\ngroup. The bold StoryId is just to help with usability in reading and\ninteracting with the document.\n\n**Examples**\n\n```markdown\n- **ISSUE-123**: New Billing Integration Service  {story=\"ISSUE-123\"}\n- **[ISSUE-123](https://example.com/issue-link/ISSUE-123)**: New Billing Integration Service  {story=\"ISSUE-123\"}\n```\n\nRemember that it is just Markdown, so it can contain links to external issue\ntrackers or anything relevant.\n\n#### Work Item\n\nThe work item is the heart of the document.\n\n```markdown\n- [ ] Item description {work=1d link=987}\n- [x] Item description {work=1h link=987 actual=1.5h note=\"note to self\"}\n```\n\nAttributes:\n\n- `[ ]` - work item is incomplete\n- `[x]` - work item is complete\n- `{link=(story)}` - links a work item to a specific story\n- `{work=(duration)}` - estimated duration to complete. The more specific the estimate, the higher the confidence. There is higher confidence in `5d` than in `1w`.\n  - Expressed as `unit` and `time`.  Examples: `1d`, `2.5h`, `0.5w`\n    - Supported values:\n      - `h` - hours\n      - `d` - days\n      - `w` - weeks\n      - `m` - months\n- `{actual=(duration)}` - (optional) actual time required to complete (for personal documentation)\n- `{confidence=(value)}` - (optional) explicitly set the confidence for the work estimate. A default confidence percent is used based on the time used. An hour long estimate has a higher confidence value than a week long one.\n- `{note=\"Text\"}` - (optional) note to associate with the work item. A note is visible on the rendered report on a work item through a \"note\" icon. It is also exposed in the \"table\" component's display of work items. Ex: `{note=\"forgotten\"}`\n- `{new=true}` - (optional) explicitly signal that something in the project structure should be treated as \"new\" when filtering, even though it isn't a work item that is directly estimated. It can be added at the top-level \"new\" item and all contained child items will be hidden when switched to the \"Existing Structure Only\" filter view.\n\n\n**NOTE:** Must be nested under a non work item.\n\n**Example:**\n\n```markdown\n- BillingSystem\n  - Integrations\n    - [ ] Quickbooks Online {work=1m link=987}\n  - Email Templates\n    - [x] Quickbooks Integration communication problem {work=2h link=987}\n```\n\n#### Filter Display\n\nDisplays a Filter radio group for changing the current filter or mode of the display.\n\nThe selection for the filter is written to the browsers local storage so it will\nremain the through a browser refresh.\n\n```markdown\nfilter {#display-filter}\n```\n\n#### Style Display Options\n\nDisplays a button that toggles the options that affect the style of the Work\nBreakdown Structure.\n\n```markdown\nstyle {#display-style}\n```\n\n##### Options\n\n- **Numbering** - Uses the traditional WBS numbering style for the list. Traditional numbering uses an outline style like \"1.1.1.2\"\n- **Bullets** - Uses a bullet list for the WBS list.\n- **Show colored deliverable checks** - Work items appear with a \"checkbox\". This option determines if they are colored or not.\n- **Show progress** - Shows progress bars at the parent level for work items. It is cumulative for all work items nested under it.\n- **Show totals** - Display the computed work totals on the WBS or not.\n\n#### Level of Detail Display\n\nDisplays a list of buttons for toggling the \"Level of Detail\" shown in the WBS.\nHelpful for \"zooming out\" to a higher level, then drilling down into a specific\narea to explore.\n\n```markdown\nlevel {#detail-level}\n````\n\n#### Story Chart\n\nCreates a chart that shows each story's work size, amount completed and\noptionally actual time spent.\n\n```markdown\nchart {#stories-chart}\n```\n\nWhen stories are toggled on/off, they are included or removed from the chart.\n\n#### Story Toggle\n\nCreates a toggle link. Helpful for flipping the inclusion of a story. If you\nwant to focus on 1 or 2 stories, you can toggle all of them off and just turn on\nthe ones you wish to focus on.\n\n```markdown\ntoggle {#stories-toggle}\n```\n\n#### Story Totals\n\nCreates a component that totals all the selected stories. Optionally it can be\nlinked to a specific group. This is effectively a sub-total then. When no group\nlink is set, it gives the total for all the checked stories.\n\n```markdown\ntotals {#stories-total}\ntotals {#stories-total group=\"Phase 1\"}\n```\n\n#### Story Table\n\nGenerates a table with all the work items' details in an easy to access way.\n\n```markdown\ntable {#stories-table}\n```\n\nThis helps get data out and easily copied into a spreadsheet or other system.\nWhen a developer is working on measuring their ability to improve at estimate\naccuracy over time, they need data. This helps collect that data for personal\nuse.\n\nThis also exposes any \"notes\" on a work-item that otherwise aren't displayed.\n\n## Troubleshooting\n\n### Error notice about local storage\n\n**Google Chrome and Chromium**\n\nSettings \u003e Search \"content settings\" \u003e Content Settings \u003e Cookies.\n\nIf you want to continue to \"Block third-party cookies\", then you can add an exception to allow access for local storage to specific files or all local HTML files. The following is a sample allow filter for all HTML pages that are loaded from your local machine.\n\n```\nfile:///*\n```\n\n## Features\n\n- [ ] Multiple chart options. A total/initial chart (where confidence represents what it was initially) and one that is \"remaining\".\n- [ ] Compute the confidence in the work that remains.\n- [ ] Give estimate on when the work might be completed based on previous estimates that are marked done.\n- [ ] Report more on estimated vs actual (where recorded)\n- [ ] For work marked done where no \"actual\" was entered, use the work value? Helps keep the \"actual\" line moving more correctly.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrainlid%2Fwbs_markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrainlid%2Fwbs_markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrainlid%2Fwbs_markdown/lists"}