TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
> Well, contrary to my personal preferences and wishes, the team
> here decided that using CVS to store my docs would be a good
> idea.
Your team misunderstands CVS.
CVS is designed for line-based computer source code and NOTHING
ELSE; it doesn't work for freeform human-language text, and it
REALLY doesn't work for non-text binary files like Framemaker's.
> They're already using CVS for code, and didn't want to migrate
> to SVN or spend the money on a new versioning system.
By this reasoning, they could write their code using Framemaker
because you're already using it for documentation... Or both you
and they could use Dreamweaver because that's what the web guy's
already using to write HIS stuff. Or better yet, why don't all
three of you just use Word?
It's a BAD IDEA to use CVS for your Framemaker files.
CVS is complicated and requires its users to adopt an unfamiliar
mindset. If it's being used for source code, those problems are
outweighed by the benefit it provides... But for Framemaker files,
it's just a needlessly complex, cumbersome, and costly archiving
program that's almost guaranteed to make you lose work or corrupt
a book.
It sounds like you're going to have to use CVS anyway, though.
> I have set up a five-layer directory structure for my books, so,
> for example, I have: Tech Documentation (Module) .ProductType
> ..ProductName ...BookType ....FM book and various book files.
As you've discovered, this arrangement has undesirable
consequences. If you only need to work on one book at a time,
it'd be better to make each book its own module.
> I then tagged the folder for each book with the version number,
> so for example the folder Product Name Reference Manual is tagged
> v381.
>
> After a half-hour's test, I've already run in the following
> problems:
>
> It seems I can only check out my entire documentation directory
> every time, and not just a particular book's folder. I've tried
> to get round this by selecting Revision - Choose branch or tag,
> but none of my carefully applied tags appear in the list, even
> after doing an Update list.
You're using TortoiseCVS? There's a "Scan subfolders" checkbox
right next to the "Update List" button. If you check the box
before clicking the button, your tags will appear in the list.
This is a bad way to do what you want, though. Better would be
to put each book in its own module.
> even if that worked, should I be tagging each file with the product
> name as well as the version number, as I'm obviously going to have
> multiple books with the version number v100?
Yes, you'll need a tag-naming convention to differentiate
between one "v100" and another.
Again, though, it would be better to put each book in its own
module.
> If I drill down into the checked out folders, I can do a check-out
> using the tagged version, but it check out the whole structure again,
> so that I end up with: Tech Documentation .ProductType ..ProductName
> ...BookType ....Tech Documentation .....ProductType ......ProductName
> .......BookType ........FM book and various book files.
>
> Is there any way around this?
Yes. Put each book in its own module.
> In addition, my Framemaker books are all labelled with the version
> number, i.e., ProductName Reference Manual v3.8.1. So each book
> file and associated generated files (TOC, LOT, LOF) are then treated
> as new files by CVS.
Right. You've always had to include a version number in the
filename because you didn't have a versioning system. Now that you
have one, you don't need to do that anymore.
> I don't want to get rid of the version number from the book, as I find
> it useful if I have two version open at the same time, but CVS is
> treating these differently-versioned files as new files every time.
> Is there anything I can do to make this better?
Yeah. Use tags to name your versions. When you checkout Book
version A, go to the "Options" tab in TortoiseCVS's "Checkout Module"
dialog and choose "Use module name and tag/branch/revision as folder
name"; the folder will be named "Book-A". When you check out Book
version B, do the same; its folder will be named "Book-B".
Each version's files will have the same names, but you'll be able
to open them at the same time or compare them or whatever because
they'll be in different folders.
-Andrew
=== Andrew Warren - awarren -at- synaptics -dot- com
=== Synaptics, Inc - Santa Clara, CA
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
