2

I have noticed a re-occurring pattern when working the processes of my software configuration management group which manages many different software baselines; however, I imagine this problem is not speciffically unique to the SCM domain.

The basic scenario:

  • A task needs to get done.
  • The documentation for a process is referenced.
  • When referencing the documentation it is noted that since the last time the procedure was performed, details have changed, or the procedure is incorrect, or because of x, y, or z this time is an exception to the process (just like last time).
  • The task still must be completed but many questions must be asked.
  • The process change needs to be documented to reflect the updated procedure.
  • After updating the process documentation, a new task takes priority.

This vicious cycle makes trivial tasks unnecessarily complicated, and creates a very steep learning curve for new hires. In my observation it also slows productivity and reduces the ability for automation and efficiency in tools and workflows in general.

Is this the norm for a software configuration management team or process documentation in general? or is there a way to break this documentation update loop?

closed as off-topic by gnat, The Wandering Dev Manager, scaaahu, Masked Man, JasonJ Aug 24 '17 at 12:25

This question appears to be off-topic. The users who voted to close gave this specific reason:

If this question can be reworded to fit the rules in the help center, please edit the question.

  • Is your job and your team's to do SCM or is it to document processes? Is documentation something another team or person does? I suppose the one developing the process is the one responsible. – DarkCygnus Aug 23 '17 at 17:37
  • 1
    @ChaosisaLadder that would be lovely, but working as a support contractor, my customer specifically requested a set of "up to date" SOPs to accompany our processes and my management happily obliged. This led to me having to update nearly 20 documents and now I am responsible for documenting any future updates to any of these procedures and doing the same for new similar ones. – John Aug 23 '17 at 17:39
  • @John I was half joking. I am working on an answer now.... – Mister Positive Aug 23 '17 at 17:40
  • What tool are you using now for your documentation? – Mister Positive Aug 23 '17 at 17:42
  • 1
    @john that sucks. – Mister Positive Aug 23 '17 at 17:44
4

Is this the norm for a software configuration management team or process documentation in general? or is there a way to break this documentation update loop?

I would make one change to your SDLC process and that would be to make everyone responsible for updating the documentation.

In order to do that you need a better tool, and I would suggest you look at Confluence. You could then also use Jira to track your tasks and tie them to your documentation. ( there are other tools like this, pick one. I just mentioned this as I have used it, * and no - I do not work for Atlassian* )

Without a change to your companies SDLC process and the implementation of a better tool for documentation, nothing will really change.

  • 2
    I agree with you, better tools definitely make it easier to carry out these tasks, +1 – DarkCygnus Aug 23 '17 at 17:56
3

Is this the norm for a software configuration management team or process documentation in general? or is there a way to break this documentation update loop?

That first part of your question I consider strongly depends on each team and what are their standards or "norms". However, a thing you could do to get out of this loop situation could be the following, based on your scenario:

  • A task needs to get done,

  • The documentation for a process is referenced,

  • When referencing the documentation it is noted that since the last time the procedure was performed, details have changed, or the procedure is incorrect, or because of x, y, or z this time is an exception to the process (just like last time).

When that happens stop, and choose another task to be done and evaluate it in a similar way. If that new tasks also presents documentation or process changes, skip it again. This enables you and your team to finish those tasks that can be done without documentation changes, preventing you from falling back on schedule on those. Think of it like the Shortest job first algorithm for (computer) process scheduling.

Given that you have a team, and you can divide tasks, you can even be more efficient, by assigning someone (or several) on the team to take care at those documentation changes for the tasks you could not complete, while the rest of the team continues with those tasks that can be finished. This way you would be working in "parallel", by getting done earlier those tasks that don't need documentation changes.

Finally, you could all continue with those tasks that require documentation changes, update the Word documents, and then proceed with the task. This will also help as not only you will be in charge of all the documentation changes, making that task more bearable. You could even check for all tasks that need document changes and divide them equally between members of your team. Remember that unity makes strength.

1

Is this the norm for a software configuration management team or process documentation in general?

For organizations that subscribe to the 'Process Model', yes, and 99% of the time, the documentation has 0 ROI due to the exact circumstances you describe. This is just bureaucracy. Keep in mind though that there may be some regulatory benefit to such schemes and that should be well known to everyone.

is there a way to break this documentation update loop?

For organizations that use the 'Expert Model' documenting the state is more important than the process because process is secondary to the result. Unfortunately, this is a cultural shift very few organizations can accomplish.

1

Is this the norm for a software configuration management team or process documentation in general? or is there a way to break this documentation update loop?

Yes, it's extremely normal.

Documentation is pretty much on the bottom of everyone's to-do list and few organization allocate sufficient time to create and maintain such documentation.

Consequently, it's often poorly done, almost always out of date, and often wrong.

Try to add time to your task estimates to account for this. And try to update the documentation every time you are required to touch it. Always leave it in better shape than when you first had to read it.

Not the answer you're looking for? Browse other questions tagged or ask your own question.