Best Practices

Simple and effective

Using Issues

An Issue List is a product focused compendium that converts many things to tasks. Github's tool is powerful yet simple, as well as naturally tied to your files. Consider it like a Kanban system for distributed knowledge work.


Ideas: It is a place to record ideas before you forget them, and discuss, refine, prioritize, and reject with documented rationale.

Concerns: Document anything you see in usage that is not as you expected.

Features: Identify each testable function as an issue.


Tasks: Any of the above can be reduced to work - described clearly enough to implement in a sitting 4-8 hours. Use the Issue document to outline a complex task, break into pieces,  and document the expected effects.

Completed Work: When a task is fulfilled the completion is recorded by the commit and pull request.


  1. Before coding anything, write an issue to explain the need for a change or start a discussion on one.
  2. Encourage comments by asking help from specific people with @githubhandle.
  3. Use Markdown to communicate effectively with headings, bullets, and numbering.
  4. Use pictures to explain, just paste them into the editor.

Automation and De-duplication

  1. When writing the issue or committing, use github's reference syntax in commit messages to refer to issues or other commits. i.e. (per #26, "Closes #30" , "Per 5dfa95")
  2. Use Reference syntax to obsolete older or less clear issues.


  1. Before working, review the fresh issues and convert to tasks where possible.
  2. Use Labels to categorize Issues that are Ready, or Nor Ready, Not Important
  3. Prioritize and Assign the "Ready" tasks periodically at the start of each sprint.


Top of page