Re: Large help projects and version control software

[Chris Gooch <chris -dot- gooch -at- lightworkdesign -dot- com>]

Steven Brown wonders:

+++
It's not clear to me whether there's a "best practice"
for "getting" versus "checking out" files when topics
need to be updated. For example, one can "get" a copy
of a file (which is supposedly read-only) but then
make it writable, seemingly allowing one to override
the "check out" feature of the system. Should we
always be checking out files, or does that restrict
workflow too severely?
+++

You should definitely use the version control system
"properly", which means checking out (i.e., locking)
a file whenever it is to be edited.   If the Version
Control system you are using is any good, then
merely making your local copy of a file writeable
should not be enough to allow you to perform a
check-in.  Speak to the software developers and
follow their practices (errr... unless they're breaking
the rules as well!).

Here we use Perforce on NT for both code and docs
(we used to use RCS on Unix). I am the only full-time
writer, but there are ~15 developers who also write docs
(I guess I manage them when it comes to docs
production). I couldn't imagine _not_ using some form
of version control (even if it is putting a MacDonalds
toy on your desk, the effect is the same).

Most systems also allow "branching", which is the
correct way to allow multiple edits on one file
simultaneously. Effectively this is like breaking locks
but in a managed way. So what software engineers
do is; person A creates a new development branch,
and the files involved are marked as being involved
in this branch. However other people (developer B,
say) can still lock / checkout and edit these files.
Eventually the work on the branch will be complete,
developer A checks back in, and the system tries to
accomodate both sets of changes. A database-driven
system like Perforce will do this in date/time order
(so it's just like re-syning a database table which has
been updated off line by 2 clients). If there were only
one check-in to a branch then the situation is no
better than if people break locks (except that you
have a branch to tie to it to, so at least you know
why it happened) but the important point is that,
within each branch, the usual file locking arrangement
continues (unless you split off a sub-branch, etc.)

Software developers typically do this so that they can
fix bugs in released code on one branch whilst
developing new code in another branch.

As mentioned by Jon Konrath, this won't work with
binary files, only text files (yet another reason to
consider xml or latex!), but further to that, for the
merging together to be without errors, the two
sets of edits (made by person a and person b)
must be seperate, or orthogonal. What I mean by
this is, that is person a takes a branch (ie. edits
without locking), and removes or renames a function
or class (and all the references to it), and then person
b locks the file (the original copy remember) and adds
some code which refers to the function that person a
is getting rid of, then when person b and then person a
do their checkins, you've got a reference to a class
that doesn't exist, introduced by person b and not
removed by person a.

I think in terms of software code this is, while not
always easy, at least _reasonably_ manageable.
I'm not sure about doing this for documentation,
however, since it seems to me that, even if your
docs are nice well structured xml, can you be sure
that the edits you are likely to make on seperate
branches? An analogy to the programming example
above (renaming a class) might be to rename a
chapter (or perhaps to changing the name of the
class in the docs as well as the code!). Easy enough
to spot if you mess up. But what if you remove a
passage of text which the later edit assumed was
there and made reference to? If the reference is an
explicit one then you should get a broken reference
or link, and hopefully Framemaker or LaTeX will
point this out to you, or you would notice in proofreading.

But what if there was no explicit reference, merely an
assumption that the reader will know the material in
the passage which has been deleted? How would you
spot this?

If anyone is still with me :-)   I'd like to ask if anyone has
any actual experience of doing this kind of version-branching
with docs successfully, and would like to swap war-stories.

I ask since there is a move afoot here to go toward rolling
releases of software, where a new feature is developed over
the course of many moons and then delivered to the customer
when it is ready, whilst other features are seperately developed
in other threads/branches. Meanwhile of course our on-line
docs should at all times the describe the product as released,
not the new functionality which is about to be released. Fine
if the new functionality is entirely additional to the current
offering (my new docs sit in a perforce branch until release time),
messy if the change needs existing docs to also alter.

I could just branch my docs-set in the same manner as
the code is branched, but as I say above, I have worries
about managing the QA of this. Anyone got any experience?

Chris.

Christopher Gooch, Technical Author
LightWork Design, Sheffield, UK.
chris -dot- gooch -at- lightworkdesign -dot- com   www.lightworkdesign.com



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out the new release of RoboDemo, our easy-to-use tutorial software.
Plus, buy RoboHelp Office in August and save $100 with our mail-in rebate.
Get details and download free trial versions at http://www.ehelp.com/techwr-l
 
TECHWR-L is supported by ads and sponsorships...and donations.
You can help maintain the TECHWR-L community with donations
at http://www.raycomm.com/techwhirl/abouttechwhirl/donate.html
 
---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.