Documentation for free
or, in-wiki issue tracking
An example
Let us say your company makes a ‘todo’ application. You use a wiki to document what the application does, and you use an issue tracker to manage future development. Here is your wiki:
‘TODO’ is a todo list application. To create a new item, type it into the empty textbox and click ‘Add’.
But your application doesn’t yet let users mark todo items as ‘done’, so you describe this feature in your issue tracker:
Issue 358: Assuming the user has created a new issue, when the user checks the ‘done’ checkbox on the issue, the todo item should be moved to the ‘done’ list.
Issue 359: Assuming the user has moved a number of issues to the ‘done’ list, when the user clicks the ‘clear done’ button, all the items in the ‘done’ list are deleted.
I want to suggest that you drop your issue tracker and instead describe these issues in your wiki. Here is how you might do so:
‘TODO’ is a todo list application. To create a new item, type it into the empty textbox and click ‘Add’. New items start out as not done. <issue>To mark an item as done, check its ‘done’ checkbox; the item will move down to the ‘done’ list.</issue> <issue>To delete the items in the ‘done’ list, click the ‘clear done’ button.</issue>
We have reworded the issue descriptions to talk directly to the end-user, then dropped the descriptions directly into the documentation at the appropriate place. The wiki can then display this markup sensibly:
Two big advantages
Let’s call these approaches ‘tracker style’ and ‘wiki style’. Both styles convey the same information: what has been done and what is still to do. But wiki-style has two big advantages over tracker-style.
First, wiki-style issues are contextual. A tracker-style issue has to describe the exact part of the application that it applies to, before it can describe the suggested new feature. But the wiki-style issues can use the surrounding documentation as context, for free. They can also use other issues as context. The wiki-style issue can be more concise and precise.
Second, wiki-style issues are free documentation. After being marked as ‘done’, a tracker-style issue falls into a black hole and dies a slow death, and your documentation becomes out of date. But a wiki-style issue lives on as your documentation. It’s not possible to implement a feature without documenting it. Using wiki-style issues forces documentation into your workflow, at no extra cost.
Unnecessary features
Now you may be thinking: ‘but my issue tracker gives me all these other issue attributes.’ Yes, every issue in your issue tracker has a title, an ID number, a description, a set of labels, attachments, parents, an assignee, permissions, affected versions, comments … whereas wiki-style issues just have an anonymous issue description.
I suggest that most of those features are only there to make up for a lack of contextuality. Wiki-style issues, thanks to context, don’t require a title, or a set of labels, or a parent issue, or anything except a short description. Nor do they require a ‘done/not done’ status, because this is conveyed by the presence or absence of <issue> tags. Nor do they require a ‘creation date’ or a ‘completed date’, because this is in the wiki history.
If the task is larger and you really need those features, you still don’t need your issue tracker, because that large task should become a wiki page, and wiki pages have those same features! A wiki page has a title, a description, labels, attachments, parents, permissions, comments, and so on. (Compare JIRA and Confluence: the same application under two names.) You can use a page per issue even for very small issues if your wiki supports transclusion.
If you really need attributes for inline issues, there are a couple of ways you could implement this. One is to introduce attributes in your syntax: <issue assignee=jhf>To mark an item as done …</issue>. Another is to give each issue an ID, like <issue id=ec6d8>To mark an item as done …</issue>, and track attributes externally. (This also allows you to put the same issue in multiple places in the documentation.)
Future tooling
For complex projects, we would want tools to help us manage our issues.
A parser would scan the documentation and generate a database of issues, where each issue includes its description, its location, its creation date, and a completion date.
A query engine would allow users to search this database, in conjunction with other databases, such as the repository. For example, a non-redundant way to track assignees is with git branches: if there’s a branch ec6d8 owned by jhf then jhf is assigned to the issue. The wiki might use the query engine to annotate issues inline in the documentation:
All our issue reporting tools (‘my issues’, burn-up charts, etc.) would query this issue database generated from our wiki.
A documentation generator would strip out the wiki-style issues to create end-user documentation. Some issues, such as bugs, could be left in so that end-users are aware of the limitations of the product:
A web application could let unprivileged users request changes and report bugs. This is done by simply letting the user edit the documentation. (If your wiki is in a git repository, feature requests and bug reports are just pull requests on your wiki!)
TL;DR
Destroy your issue tracker. Put your tasks directly in your documentation. Task descriptions are just future documentation. Documentation for free!
