Our current user's guide is built using asciidoc. The documentation is managed by a non-technical person, but we keep the source text files as well as generated HTML in source control. Issues arise when they are making doc updates for version x.z in the x.y branch. Typically, one of the developers will update their environment, but they can be very forgetful. I know there has to be a better way to do this.

How do you manage users' guides in a versioned manner without actually depending on non-technical users to learn VCS?

  • How non-technical can someone who is writing technical documentation be? She can understand the system well enough to explain it to the users, but she cannot figure out version control? – Matthew Flynn Mar 14 '12 at 22:03
  • It is not technical documentation; it's a users' guide for a product for people who are also far from technical. – sarumont Mar 14 '12 at 22:15

When your documentation is under version control, it is typically not an unreasonable request for the person doing the documentation and/or managing the documentation to ensure that it is properly checked-in -- be they a technical developer or otherwise.

In my experience, a sticky note on the desktop (virtual or not) with the few git/svn/etc commands, or the interaction path with one's GUI client of choice, on the desktop of an otherwise non-technical person has worked just fine when the responsibility and expectation is made clear that documentation checkin is part of the job.

You may not be able to do this in your specific situation, but if we took out the "my husband is the CTO and does some things for me" (note: this was in the original question) and tackled the issue in general then some options include:

  • The person learns how to use version control and it is made part of their workflow, as noted above (and again, not unreasonable, although the project manager or technical lead or whomever keeps an eye on things might have to keep an extra eye on things the first few times).
  • The person doesn't learn how to use version control and the workflow step for documentation check in falls to someone on the development team or perhaps the release manager (depending on when the checkin happens).
  • Something else probably more convoluted and inefficient than keeping a sticky note on the desktop about how to checkin a document...
  • I'll probably give #1 a go this time around to see how it works. I have a feeling, though, that her environment may be a bit convoluted (requiring more than a few commands on a sticky note). – sarumont Mar 14 '12 at 19:21
  • 1
    @sarumont Perhaps so, but really, I've had even the most non-technical person be able to follow along eventually...no need to mess up everyone else's workflow (or the product) because one person can't. Good luck! – jcmeloni Mar 14 '12 at 19:24
  • @sarumont: if a few commands on a sticky note are not enough, there seem to be a problem which has nothing to do with version control. Those problems you will also face if you would not use version control to hand the docs over (for example, by mail or by using a shared server folder). – Doc Brown Mar 15 '12 at 7:27

Well, in which branch should she actually make doc updates? In x.z, in x.y, or in both? If there is just one branch, restrict her access to that branch at your VCS server. If she has to work on both branches in parallel, better teach her a bit more about version control, and make sure it is easy to see which branch she is currently working at.

  • She needs to make them in x.y; x.y is code-frozen while QA does regression tests and documentation is updated. Once x.y.0 is released, I'll merge x.y forward to x.z to capture all the bugfixes and documentation changes. – sarumont Mar 14 '12 at 19:12
  • 1
    @sarumont: Well, in this case, if she gets no access to branch x.z, she cannot change the wrong version. That simple. – Doc Brown Mar 14 '12 at 19:53
  • oops - I misspoke. x.y.0 (and further patch releases) are out the door. x.z is in staging/beta/slush and x.a is in active development. So the documentation needs to be updated in x.z, not the older x.y. Your comment suggestion is still relevant, though, but I fear our VCS setup may require additional work for that sort of ACL. Thanks! – sarumont Mar 14 '12 at 22:20

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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