Associate User Docs With Source

(From an idea by SteveJorgensen on LocalityOfReferenceDocumentation)

For every piece of source code that implements user-visible controls or functionality, include HotComments that associate a "documentation tag" with the source. The documentation tag is an opaque string that identifies a specific feature that needs to be documented.

When a feature is documented, tag the docs with the same documentation tag.

Then you can have a UnitTest that fails (or just warns) whenever a tag exists in source code but not in the docs (an implementation for a user-visible feature exists without any corresponding documentation) or vice versa (functionality has been removed but is still documented).

This creates at least some ties between the two, while dealing with the initial objections I had to keeping user docs in the source code (see below).

The sticky point is keeping the user docs updated. When the source code changes, there must be some mechanism to "invalidate" the corresponding docs so the person responsible for them at least has to look at them to see if they need to change. One idea is to have the programmer "version" the tag (for example, change "graph_editor" to "graph_editor_2") so it's no longer found in the docs.

It would be really nice if adding and/or updating the tag could be automated somehow, but it's not clear to me how yet... comparing file last modified times seems way too simplistic.

Original discussion

(In reference to LocalityOfReferenceDocumentation)

...agree for internal/process docs, but STRONGLY DISAGREE for use docs, mostly for reasons similar to those listed above:

# The user docs are not an artefact of the source code. They are an artefact of the user experience, and so should be much higher level than any class, method, function, whatever (with the possible exception of reference pages documenting every option in a window). The writers never need to see the source code to write the docs.

# Even if this helped the programmers spot a place where the change they just made to the code necessitates a change to the user docs, they need to tell the writer, because they shouldn't ever mess with the docs. (Sorry, I've had too many programmers helpfully rewrite my docs into PassiveVoice? to "make it sound more professional".)

# This is more vague, but trying to do this with user docs unless every single member of the orginization is 100% totally on board is a recipe for disaster. The developers will hate having a bunch of text littering their source code that needs to be preprocessed out, and the writers will hate having to deal with source code, text files, not being able to use their tools (e.g. FrameMaker), and not being able to see/edit the docs as a coherent whole.

-- MattChaput (tech writer)

What you say makes perfect sense, but here's a problem. The trouble with any documentation that has no structural connection to the code is that when a change is made to the code, the documentation frequently won't get updated, and there's no way to see what needs to be fixed aside from an exhaustive UI test-drive and comparison of the current UI and requirements to the existing documentation. Unless there's some mechanism for automatically detecting that the match between implementation and documentation is now broken, documentation gets out of date.

Just thinking "out loud" here, let's say there is something called a UserExperienceTag? that appears in both the requirements document (FitNesse tests and commentary or whatever) and in the user documentation. When a requirement is added that will affect the user experience, a UserExperienceTag? is added to the requirements document. Subsequently, a validation check will show that there has been a change that is not indicated as having been addressed in the user documentation. Similarly, if a requirement is removed, the validation will show that the user documentation still includes reference to a feature that no longer exists.

The documentation would not be required to mirror the requirements in any strict way, just have a tag somewhere next to the text that covers the explanation of the requirement. If one paragraph covers 2 requirements, it can simply have both tags. If multiple places in the documentation refer to a single requirement, the tag can appear in all those places. The automatic comparison of requirement tags to user documentation tags would simply make sure that there is a strict 1 to [1 or more] relationship between tags in the requirements and in the user documentation.

For projects in which (wisely or not), the developers are responsible for the user documentation, the validation of user documentation could happen during the build process. To address your valid concern about programmers inappropriately editing user documentation when that's someone else's job, the user documentation and the process for validating vs requirements would be kept outside of the build tree, and not integrated with the build process, and the documentation maintainer should run the validation as a part of his/her regular activities.

Again, this is all thinking "out Loud", and I'm not aware that it's ever been done, but it certainly seems practical, does it not?

-- SteveJorgensen

Steve, I'm just thinking out loud here, but the idea of "tags" sounds bloody brilliant! I wish I was still working in an agile shop so I could incorporate this idea into my workflow. I'm still going to try to think of a way to do something like this in my current not-very-agile-and-no-unit-tests environment. -- MattChaput