Our team of writers use the same system, although as we are using FrameMaker we lose some of the nicer features but the core reasons for using a version control system remain - files are locked by whoever is working on them, and we have a full version history of changes made, including when, who and why.

We use Subversion which, when I joined the company, I’d had no experience with. However the basic premise is simple, you store the master files in a central repository and everyone uses a client to manage a local working copy (updating and locking the central repository as required). TortoiseSVN is our client of choice, which offers a simple right-click menu to access the required functionality. One advantage of this system is simplicity as it is a file-based, single lock system, so only one person can work on a file at a time, ideal for most technical writing teams.

Presuming your files are already in the central repository (there are many guides on how to do this, it is very straightforward) you first need to create an empty folder on your own machine, this will be the local working area. You then checkout a copy of the master files from the central repository to your local working area. The checkout process will mimic the folder structure used in the central repository, and Tortoise will now start to apply rules to those folders (more on that in a bit).

It’s important to note that once you have checked out files locally, they are still under version control. To delete or add files to this local area, you will need to use the options available through Tortoise (right-click a folder or file in that area). Files and folders under version control will have an additional icon to indicate their current status.

To work on a file (or files) you must first lock it in the central repository, then open it in your preferred editor. If there is a newer version of the file in the central repository, you will be prompted to update your local copy first. Once the file is locked you can edit it as normal and when you are finished and have saved the changes, simply close the file, right-click and select Commit. The changes you’ve made are updated back in the central repository and the file is unlocked for others to use.

We currently use FrameMaker and it works fairly well with this system, although there are some limitations. As the file format FrameMaker (or Word for that matter) uses isn’t binary, then you can’t use various commands so no merging of documents, for example. However if you need to maintain multiple versions of the same document it works well.

There are a couple of gotchas though, and we use a combination of SVN (Subversion) locking and the CheckFileStatus plugin for FrameMaker to get a process that works for us.

The plugin simply flags whether the file you are opening is read-only or not, and as SVN locking simply sets that property on the selected file, it’s enough to catch whether you are trying to work on a file that hasn’t been locked. In other words, all the files in your local working area are read-only until you lock them and remove that property. Once locked the files are no longer read-only and the plugin will allow you to open them to work on.

It does mean that you need to set an SVN property on the files you have checked out which will mean you CANNOT edit any files until you have requested a lock from SVN. This way only one person can edit a file at a time, which suits our needs (as we cannot use the ‘merge’ functionality in SVN).

To add the property:

1. In your local checkout directory, right-click a folder, and select Properties.
2. On the Subversion tab, click Properties.
3. Click Add… .
4. Enter the property name (you’ll need to type it) “svn:needs-lock”.
5. Enter a property value of *.
6. Select Apply property recursively.
7. Click OK, then OK again.
8. Close the Properties dialog.

Note: SVN doesn’t actually apply this setting to the folder, just the files within it.

And that’s it, you are ready to go. To work on a file, or set of files (like a FrameMaker book and chapters), select them in your local working area, right-click and select Get Lock… . Once locked, you work with the files as normal and once you are done, right-click and select SVN Commit… .

Done. Hope this was helpful.

It’s a little different here on this blog though.

I’ve just re-read my previous post (the big long one below) and it strikes me that while it may be interesting to some it suggests I may be at a point in my career where I need to practice a little more of what I preach.

In other words, I need to start to try to do all these things I’ve mentioned, rather than theorise and prevaricate over the nuances. But then that’s a bad habit of mine.

Sometimes you just need to put up or shut up.

I question everything. It’s part of the way my mind works, and is something I’ve embraced and believe it makes me better at my job as a technical communicator. That attitude has also helped me realise that there is a common thread that can be found across several different areas of our industry, which I (and others) are slowly pulling together. Convergence is the word that springs to mind, and as businesses clamber onto the social networking bandwagon, now is an excellent time to grab the reigns and take control.

Let’s step back a little.

Late last year, on two separate mailing lists, I followed discussions about what the myriad of people who share my profession have as job titles. I prompted one discussion on the ISTC mailing list, and chipped in some thoughts on the TechWR mailing list before dropping out later on when the noise ratio, as ever, got too high.

I wonder how much useful information I miss when I do that? Ahhh something else to ponder. But not today.

Anyway, discussions around how we as a profession should be referring to ourselves, envitably leads to discussions and thoughts about what we do, where our skills lie, and the benefits we can bring to an organisation. Something I’ve toyed with before, but which is wrapped up in many layers of ifs, buts and other such caveats.

Following on from that, I read an article by Virginia Lynch in the CIDM newsletter (and if you aren’t subscribed to their newsletter, you should be) entitled Information Developers - The New Role of Technical Writers in a Flat World which encapsulates a lot of my current thinking on how to take my current team forward, making sure we are matching company strategy whilst allowing the team members to retain a focus on maintaining and developing their core skills. The article title rather neatly alludes to Thomas Friedman’s book The World Is Flat: The Globalized World in the Twenty-first Century which is certainly worth a read.

Virginia mentions that JoAnn Hackos recently referred to these core skills as “Basic Hygiene”, citing the fact that, regardless of how the collation and production, distribution and usage of information may change, as we explore the burgeoning arena of new tools available to us under the banner of “social web applications” our core skills remain. Typically they tend to drop off as we are pushed to create more, faster, with a rise in quantity favoured over a maintenance of quality.

style, grammar, punctuation, spelling, and even clarity seem to have been sacrificed for quantity —JoAnn points out that knowledge of basic writing skills is still critical to our success as writers. Basic Hygiene also comprises an understanding and appreciation of editing, the information development life cycle, fundamental web and computer skills, and of course attention to detail.

However it is important to note the nod towards quantity being a business leader, and those of us tasked with managing a team need to consider how we achieve that business aim, without impacting our integrity as Technical Writ… umm… Information Developers?

So, how do we produce more whilst maintaining quality?

Wait! What’s that coming over the hill? Ahhh yes, the shining white knight of single source, armour gleaming, his trusty DITA (or DocBook) in hand, ready to do battle against the ills of productivity measurements and over-zealous QA departments. What else were you expecting? Ohh more resource? No, not these days when everyone is a “content creator”, not these days when we should be embracing and encouraging our audience to help plug the gaps in our information dykes (I really must stop mixing my metaphors).

Topic-based writing certainly seems to tick the required boxes and every business case and ROI I’ve read (and I’ve written a couple myself) points us towards the promises found over the horizon and the “he’ll be here real soon, honest” arrival of the aforementioned white knight. The trouble is that, whilst it is easy to agree with the theory, I’m not all that sure the white knight is all he seems. Certainly as we climb the hill towards him, auditing our content, deciding on chunking levels, agreeing metadata requirements, we begin to see that that armour seems a little thin and dented in areas, and I’m not entirely sure the knight is filling that armour as much as he should. Aren’t they supposed to be big strapping warriors? He looks a little weedy to me…

Topic driven content written with a minimalist slant, deferring here to the instructions of Strunk and White* rather than Roy Carroll, are where we seem to be (need to be?) heading and that’s fine and good from where I’m sitting.

* A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he avoid detail and treat his subject only in outline, but that every word tell.

On the flip side, there is a definite growth in awareness around the use of Web 2.0 technologies and systems, building online communities, integrating Wikis, blogs, RSS feeds into the information flow either as part of end user deliverables or as methods for encouraging information creation by everyone involved with the product, internal or external.

A large part of our job concerns the collation and filtering of information so as far as I’m concerned anything we can do to make the creation of source information easier has to be welcomed. Extending these mechanisms beyond internal usage means it should be easier to provide information to the people who really need it, with the added bonus of a greater level of trust in that information. Don’t believe me? Which type of information do you put most weight on, the information passed to you by a trusted colleague who you know uses the product heavily, or the product documentation? (and bear in mind that we technical writers pre-disposed to favour the work of our peers). That in itself is another issue which may be alleviated by embracing social content creation, pulling on the goodwill generated by openly inviting contribution and collaboration, whilst giving technical writers a chance to show their worth in full public view.

So where is all this heading? I’m not sure if anyone is too sure but there do seem to be some trends appearing. The use of Wikis to host documentation, the creation of community websites with few restrictions, and more. There are plenty of tools, and with a little work you can get them talking to each other. Technology is not the limiting factor anymore, attitudes are now the only things stopping us trying these wonderous new things. It’s a big step for some companies, and some people, to free their information, to pass their hard earned knowledge about willy-nilly without a clue as to how it will be used.

Once you’ve gotten past the limitations, the real effort, once you have your community or collaboration up and running, is the surrounding processes. Do you want to pump content into the website regularly? (yes). Do you want to allow anyone and everyone to contribute to that same store of information? (yes). Do you want to allow others to quietly correct your mistakes? (yes). Do you want to give the people who need it, access to information about your product, regardless where it originates, trusting them to use their judgement? (yes).

The final pieces of the jigsaw are the finer details of implementation. Presuming we want to reuse information as often as possible where do you store information and how do you allow access to it? Who should be involved in verifying new information? Where/how is the level of trust established?

Pulling together the threads of this emerging role is tricky, with so much overlap into multiple areas and so much to consider there is a danger of not seeing the wood for the trees. This post is an attempt to step back and make a little more sense of what I can see, what I know, and the changes starting to drag our profession in interesting new directions. I fear I may have muddied the waters, but hopefully they’ll settle and things will start to make sense.

Regardless of whether I’m right or wrong, one thing is for sure, these are exciting times and we have a great opportunity to finally leverage technical communications into the spotlight. The value of information is finally being properly realised, and we are ideally placed to help any organisation make the most of what information they have and help them understand and create the information they really need.

Well not just me, but my interpretation of the instructions which were a little vague in one key area. Namely, where to start. This is crucial as, most laminate flooring needs to be laid the correct way to make it possible to snap all the pieces into place. It’s a one-directional jigsaw puzzle, if you will.

The details here aren’t important, but what it taught me (for the umpteenth time I guess) is that documentation needs to be complete, unambiguous and for hardware related matters at least, a picture tells a thousand stories.

I keep going back to the assumed knowledge angle, and it rings true for this example. One of the forums I found during a frantic Googling session yielded a comment along the lines of: “The professionals know this but it’s not something you’ll find in the instructions”.

I have been guilty of this in the past. Presumption is the silent virus that can kill an otherwise excellent piece of documentation stone dead. All it takes is one presumption to render an entire document AND THE PRODUCT IT IS SUPPORTING, next to useless (or at the very least “problematic”). Introducing that kind of negative thinking at an early stage of the product lifecycle makes it very hard to undo.

Although that, itself, is a presumption. I’m presuming that most people only read the documentation when they are still novice users. So maybe that is another presumption that I need to work on removing.

9 ways to gather user feedback
It’s often a struggle to get true user feedback on your documentation, Craig Haiss offers some suggestions to improve things in this area. Whilst I’ve tried some of these, and had heard of them all, it’s worth a look to jog the memory:

You can write the most detailed instructions in the world, but if they aren’t the instructions users actually want, you’re wasting your time. That said, how do you go about gathering feedback to flesh out your documentation?

Tech Comm Job to Job Title: Something Lost in Transit?
Ben Minson is musing on job titles and, as well as raising a giggle, ends up stuck. Job titles, as a way to convey what you do for a living, are important.

… the dictionary says one who documents is a “documentalist”—however, I’m reluctant to adopt a job title that includes the word “mental.” So this is where you get “documentation specialist.” The same goes for “usability specialist.”

It seems a little funny that, being writers at heart and therefore professional manipulators of language, some of the terms we pick for our field don’t easily translate into job titles.

I’m currently experimenting with the title “Technical Information Manager” which is a little OTT but seems to fit my current role, thankfully my company, like myself, isn’t hung up on formal job titles (they prefer that you, you know, get on with whatever needs done). So, what’s your job title?

Typography humour

Glossary of DITA terms
Bob Doyle is wondering if there should be a central, user-maintained, glossary of DITA terminology:

many DITA-related terms are not defined … They are simply assumed.
And some is insider jargon, like reltable for Relationship Table.
And there is no convenient alphabetical listing.
You can search for terms on the DITA Infocenter, but then you have to already know the term.

This got me thinking. If you have been toying with setting up a documentation Wiki, then this may be an excellent place to start. It might also throw up some interesting usage of terminology. Definitely something I’m going to have a stab at (well, I’ll add it to the list of things to try).

RoboHelp vs Flare
Interesting round up of posts and comments on this topic. If you use, or are planning to use, either product, give it a look.

And I’m done. Another week in the wonderful world of Technical Communications has gone, I wonder what next week will bring?