6

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?

2
  • 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? Commented Mar 14, 2012 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
    Commented Mar 14, 2012 at 22:15

2 Answers 2

7

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...
3
  • 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
    Commented Mar 14, 2012 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
    Commented Mar 14, 2012 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
    Commented Mar 15, 2012 at 7:27
0

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.

3
  • 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
    Commented Mar 14, 2012 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
    Commented Mar 14, 2012 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
    Commented Mar 14, 2012 at 22:20

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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