Docs: Folding review into the normal dev process?

ForgeRock Community Logo Perhaps you have read the recent updates to the community development process page. In a nutshell there’s a push to doing review-then-commit rather than the other way around.

As I described earlier, we currently use a doc-specific review process to ensure technical accurate and complete core docs at the time of release. The doc review process sits alongside the standard development process, and so requires a bit of extra work in management and tracking. Also, as long as the doc review process sits outside the main development process it will not be as easy to track as the rest of the work.

Should we fold the doc review process into the normal development process?

Review-then-commit certainly promises to reduce the additional workload in tracking and managing dev review. In theory if we manage to commit content that is ready for validation testing at the same time as the code it should ease the burden on people doing testing and validation. Perhaps testers will not have to switch context back to features studied much earlier. They might even find the doc useful when working with new features.

The downsides don’t seem insurmountable. Design review, really part of product definition, still needs to be tracked separately. But once design review is done, it can result in JIRA issues that we handle like the rest of the work. For validation testing, quality assurance might prefer that writers track coverage. Or perhaps that will be part of the test plan. Either way seems fine as long as the work is not falling through any cracks. There are also a few documentation updates where IMHO review-then-commit is just overkill. Commit-then-review is no doubt the best approach when fixing typos, for example. Commit-then-review might also be best for editorial fixes and indexing, too.

So I’m tentatively guessing that although it is a significant shift from what we have done so far, folding doc review into the normal dev process will improve quality and save effort. I’ll be trying to stick closer to the standard development process starting with OpenAM 10.1.0 (and associated policy agent and OpenIG docs).

What do you think?

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s