Multiple documentation issues in a single bug

Question

It is clearly a bad practice to incorporate several issues in a single bug. It is not convenient, hard to maintain, difficult to keep track of what is done and what is not, etc.

But does all this concern bugs associated with documentation as well? By documentation, I mean only external documents (user guides, architecture overviews, etc.). I personally find it more convenient to create a single bug for multiple issues in the same document. It's easier to keep track of the updates in the document and review the document when the changes are done.

What are the cons of incorporating multiple issues of a document in a single bug?

Answer 1

They're the same as conflating problems in code. The only difference is that one of them (changes in one place having unintended consequences in another) are slightly less like to occur in text than in code.

Most developers view computer code as an active, dynamic entity whose behaviour is not readily predicted and which you cannot understand properly without running it in the context of testing and production, and rightly so. But most developers also assume that text is a static, trivial thing which you can understand just by looking at it, and which you can therefore correct trivially without having the larger view. That is somewhat true, but even in text you need to preserve coherency (e.g. for ubiquitous language as defined by DDD), keep references intact, and be wary of unnoticed self-contradictions. Therefore documentation also profits from being changed in one way at a time, and with an understanding of the entire "code base".

Answer 2

Cons appear when document changes are versioned (and when they aren't, anyone responsible for quality assurance will have tough time verifying whether issues are fixed or not) and when particular doc version integrates fixes for only part of the issues listed in the original bug.

Cases like this may become hard to track:

^{Issues listed in bug under 1 through 20 were resolved in version 25, but issues 15 and 17 reappeared again in version 27 and later, issues 40 through 50 were resolved in version 31, issues 70 through 80 were resolved in version 118 of the guide.}

Worth noting that above doesn't mean that one necessarily has to open a dedicated bug for every single issue they discover. You're not alone finding it "more convenient to create a single bug for multiple issues in the same document" - in my experience it was typically the case in doc reviews: one studies the doc, lists the issues and puts them in a single bug for further tracking.

The way out that has been proven to work well to me is to allow for splitting the original list by extracting part of the issues into new, dedicated bugs as convenient, making it clear to the readers of the original bug where the "extracted" issues went.

---

Say, if one expects that next version doc is going to address 10 of 100 issues listed in original bug, then one can create a new bug that lists only these 10 issues and edit the original bug, informing readers that 10 issues are going to be addressed separately per new bug.

New bug clearly separates the issues to be checked and verified in a given release, while update made to original bug de-scopes these issues, leaving remaining 90 to deal with.

When 90 of 100 issues are expected to be addressed, approach is essentially the same, one "extracts" remaining 10 issues into a new, dedicated bug and proceeds with handling 90 issues that are relevant to coming doc version, using original bug to track the progress for these 90 issues and to inform reader that other issues are to be addressed per separate bug.

The way how list is split basically follows the way how issues are addressed in consequent doc versions; parts of the list that are expected to be handled in particular version are "extracted" to simplify tracking of how these are fixed.