jump to navigation

A default Single Source Layout. What’s the point? 29th October 2009 (Thursday)

Posted by Colum McAndrew in Adobe, RoboHelp.
Tags: , , , , , , , , , , , ,
2 comments

If you have only ever created a new project whilst specifying the output layout to be produced in the process, this is a question you may have never had to ask. However if you’ve had to change the output layout being produced from your project (e.g. for Microsoft HTML Help to WebHelp) or you output two or more different layouts, you will almost definitely have had to address this.

On the face of it, your default single source layout allows you generate your chosen output by clicking a single toolbar icon. This is all very handy if you don’t have the Single Source Layouts pod displayed at the time but it is so much more than that. It also controls your project windows and table of contents properties.

Take start with a look at your humble window. Isn’t it just a container in which you display your help? Unfortunately it isn’t quite as simple as that as the default single source layout at the time the window was created determines what window characteristics can be changed. The reason for this is that web based output (e.g. WebHelp) uses a browser to display the help contents.  With a CHM file you have much more control over the window used to display the help because it is a single compiled locally installed file.

As well as this, the window properties available differ. As web or flash based output requires a skin to control much of the look and feel of your output, the window definition needs minimal supervision. For example the skin controls colours, buttons, fonts, etc., whilst the window controls placement, default tab and properties when viewed from a context sensitive help API.  With Microsoft HTML Help (.CHM) output it is the window that controls the buttons that are displayed as well as the look of the tri-pane container.

As for your Table of Contents, the default single source layout controls the properties of your books and pages. If Microsoft HTML Help is your default layout you can assign different book and page icons in the Advanced tab via the “Image” field. This is not available with other layouts.

Hopefully now you understand that your default single source layout controls so much more than the default output produced. So if you ever face a situation where you can’t change the properties of your Table of Contents or help window, check your default single source layout setting. Changing your default is as easy as right clicking on the single source layout (in the Single Source Layout pod in RoboHelp 7 or later) and clicking “Set as Primary Layout”.

Importing a PDF into a RoboHelp Project 28th October 2009 (Wednesday)

Posted by Colum McAndrew in Acrobat Professional, Adobe, RoboHelp.
Tags: , , ,
add a comment

Some users have had issues importing a PDF into a RoboHelp project. This is normally where a PDF created in an old version of Adobe Acrobat (e.g. Acrobat 6) is being imported into a RoboHelp 8 project, or a PDF created in the latest version of Adobe Acrobat (version 9) is imported into an older version of RoboHelp (e.g. RoboHelp X5). Normally the user gets an error message such as “Unsupported or corrupted file” yet the PDF opens perfectly OK in Adobe Acrobat. What gives?

This is one of those occasions where the error message is slightly misleading. The issue with it is that it is ones natural reaction to focus on the word “corrupted” with all the connotations that it brings. However the word “unsupported” gives the real key to the problem. In the above scenarios you have a mismatch between the product versions. As Acrobat 9 was released after RoboHelp X5 and RoboHelp 8 was released after Acrobat 6 I guess you have to suspect problems with backwards compatibility. It’s a bit like installing your old DOS Asteroids game on Windows 7 and expecting it to run flawlessly!

So how do you get around this conundrum? There are a couple of workarounds:

  • If you are importing your PDF into a RoboHelp 8 project, get hold of an earlier version of Adobe Acrobat from which to create your PDF. Another option is to use one of the many free PDF convertor tools to be found on the internet.
  • If you are importing a PDF created in a newer version of Acrobat into a older version of RoboHelp (e.g. RoboHelp x5) you have a couple of options:
    • The first is to print the PDF to the Adobe Printer print driver, saving the file as a PDF. Reports have indicated that the PDF imports into RoboHelp with no issues.
    • If you have access to Acrobat Professional, use the Optimizer function saving the file as an earlier PDF version. Creating a PDF in this way takes slightly longer but also works well. Note however that this method removes and invalidates any digital signatures.

Forgotten User Passwords on RoboHelp Server 8 26th October 2009 (Monday)

Posted by Colum McAndrew in Adobe, RoboHelp Server.
Tags: , , , , ,
add a comment

A few months ago I saw a user wanting to know if they could retrieve the password issued to a user accessing an area on the RoboHelp Server 8. This is a reasonable question considering that the UI of the Web Administrator does not allow you to edit a user once it has been added. So if you have created a user, and emailed them a password but not recorded it anywhere, there appears to be no way of finding out what that password was should it get forgotten or lost. What is more, deleting the user and re-adding them is not allowed as the RoboHelp Server database still has a record of it.

I thought there probably was a way to rediscover a user password, if not in the UI then under the hood so I emailed Tulika Garg at Adobe to find out where. The response back said that there was in fact no provision for finding out a forgotten password. Once it was lost, it was lost for good. However as a workaround, you can edit the RoboHelp Server database as follows:

  1. Open the RoboHelp Server database.
  2. Find the TRobouser table.
  3. Look for the table row that has the ru_UserID value of the user whose password is forgotten.

The result of this is that you are able to add the user again via the Web Administrator and prompt you for a new password. Of course it goes without saying that taking a backup of the database is a precursor to the above procedure. Better still create a text file somewhere where you can record the userids and their passwords.

Deleting Legacy WebHelp / WebHelp Pro Output Files 23rd October 2009 (Friday)

Posted by Colum McAndrew in Adobe, RoboHelp.
Tags: , , , ,
3 comments

My wife and I have a running joke about how we organise things. I like order. It’s a man thing I guess. CDs are in racks sorted alphabetically by artist and books are sorted by genre and then size. It’s neat, tidy and easy to manage. Her method of organising is to have lots of piles of stuff littered everywhere. What is even worse is that she knows exactly in which pile that receipt for £2.49 for a cheap brooch bought nine months ago is! I digress!

When it comes to RoboHelp WebHelp and WebHelp Pro output files I am equally as anal. Things are a little easier of course as the files are very handily located in a folder all of their own and are generated / published to a location of your own choosing. But over time you can end up with lots of erroneous files. Take for example a project that is generated and published for the first time. Everything is brand spanking new and the output files are exactly what you require. Move on a few project versions and you may have renamed topic files, deleted baggage files, amalgamated map files, deleted index and/or TOC files. In fact just about any change to a project can result in a previously generated / published output file to be redundant. To make matters worse, because of the publishing workflow you have a duplicate of everything. Your generation directory has the output as it was created by your Single Source Layout. Your published location has a copy of it. So to delete files you have to go to both locations via Windows Explorer and manually delete them.

Of course if you are not bothered by redundant files it really doesn’t matter. They don’t do any harm apart from clogging up disk space, but me being me I like to keep things clean. The problem is, there is no way to clean up redundant files from within RoboHelp. This is a bit of an oversight in my opinion and some single source layout option to delete them would be useful. Maybe I’ll go and submit another feature request before filling a copy away in my Microsoft OneNote notebook; filed alphabetically of course ;-)

RoboHelp Server 8 Area Directories 22nd October 2009 (Thursday)

Posted by Colum McAndrew in RoboHelp Server.
Tags: , , ,
1 comment so far

I happened to be looking around our RoboHelp Server box the other day and decided it would be useful if there was a shortcut on the desktop to the location of our help output when it is published. The trouble was, where was it placed?

The properties of the WebHelp Pro single source layout gave me some clue. After all it provided the path to the server and the area to which we were publishing. With that information it shouldn’t be that difficult. I started digging around the C:\ drive and discovered the following directory:

C:\Program Files (x86)\Adobe\Adobe RoboHelp Server 8\robo\server

Now I was on to something, especially as I also discovered that there was a sub-directory to it that mirrored one of the areas we had published to. Whoopee! But just as I was getting carried away with excitement (yes I know it is sad to get so excited over such things) what should I discover but the following directory:

C:\Program Files (x86)\Adobe\Adobe RoboHelp Server 8\robo\secure_server

Oh! Hang on a minute. What is this? It too has sub-directories that mirror areas to which we have published. What is more some areas appeared in the secure_server whilst others appeared in the server directory. None appeared in both. What was going on?

Then all of a sudden I had a hunch. Could the difference be whether an area is protected in the Areas dialog of the Web Administrator? I created a new area ensuring I ticked the “Protected” option. Having published some output to it, lo and behold it appeared in the secure_server directory. If I made the area unprotected and published the output, it appeared in the server directory. I had cracked where to point my desktop shortcut.

In summary, output is placed in the following server directory:

  • Protected:  C:\Program Files (x86)\Adobe\Adobe RoboHelp Server 8\robo\ secure_server\areaname
  • Unprotected: C:\Program Files (x86)\Adobe\Adobe RoboHelp Server 8\robo\server\areaname

Twitter versus LinkedIn Groups 17th October 2009 (Saturday)

Posted by Colum McAndrew in Technical Writing.
Tags: , ,
add a comment

In the red corner, weighing in at 150 pounds and 101 connections, the established professional social networking site that allows people to network within groups and sub-groups, the heavyweight world champion, LinkedIn. In the blue corner, weighing in at 135 pounds and 1005 followers, the less talented yet exciting young pretender that has taken the world by storm, Twitter. Seconds out, round one!

The arrival of Twitter on the scene has upset the apple cart when it comes to more established methods of social networking sites like LinkedIn. Whilst their overall objectives are different, the less structured environment of Twitter together, short and shappy user interface together with its instant communication makes it the sexy beast that everyone wants to be with.

If ever this had to be demonstrated, you could look no further than a comment made to me this week. Recent activity on my LinkedIn profile had shown a couple of things. Firstly, a connection of mine who used Adobe products had joined one of the LinkedIn groups connected with their products. Following a discussion with them on the plethora of LinkedIn groups on Adobe products came the slightly tounge in cheek answer, “Why can’t they all use Twitter and be done with it.” Secondly a LinkedIn group I belong to had a discussion on whether to set-up sub-groups for those with a specific focus.

Of course both Twitter and LinkedIn are very different beasts and each has its specific uses. The problem is though that there is a certain amount of crossover. OK the 140 limit of Twitter may not suit all your needs but the sheer size of your potential audience can make it a quick, easy and effective way to desemminate information. That said, the art of networking is better suited to Linkedin. Use Twitter over LinkedIn? No I don’t think so. They are all grist to the mill.

The Development of Breadcrumbs 9th October 2009 (Friday)

Posted by Colum McAndrew in Adobe, RoboHelp.
Tags: , , , , , ,
1 comment so far

The use of breadcrumbs in RoboHelp projects is a popular method of providing an alternative navigation aid for users. They were relatively late on the scene, not arriving until RoboHelp 7, by which time they were in fairly wide use in web design. Despite this many RoboHelp users leapt at the opportunity to use them. And why not?  They were simple to set-up and use. You just enabled or disabled them and they were displayed in your topics accordingly.

With RoboHelp 8, things are a little more complicated because of the additional possibilities that this functionality area now provides. For example in addition to adding them globally throughout your project you can add breadcrumb placeholders to a:

  • Master Page
  • Topic
  • Header
  • Footer

Additionally if you use a master page, you can insert a breadcrumbs placeholder either inside or outside of the body placeholder. If the breadcrumbs placeholder is inside the body placeholder, only topics initially created using the master page will output your breadcrumbs. What this means is that if you previously didn’t use the breadcrumbs placeholder, adding it to a master page inside the body placeholder and applying the master page to your topics, does not output breadcrumbs for those topics. To achieve getting breadcrumbs appearing in old topics to which a master page is applied, your breadcrumbs placeholder must be placed outside the body placeholder.

All of this is fine but what if you have moved the breadcrumbs placeholder around your master page? For example say you placed it inside your master pages body placeholder. In this instance, all new topics created with the master page would contain a breadcrumb trail. If you then moved the breadcrumbs placeholder to outside your master pages body placeholder, the topics created from the master page before you changed it would now have two breadcrumb trails. What is more, if you applied breadcrumbs globally you would end up with not one, not two, but three breadcrumb trails.

What do you do if you encounter this? Basically it is time to get up close and personal with your topics. Each topic created using the master page will have to be changed to remove the breadcrumbs placeholder from the topic content.

Creating RoboHelp Server Areas 8th October 2009 (Thursday)

Posted by Colum McAndrew in Adobe, RoboHelp Server.
Tags:
add a comment

A topic that has come up on more than one occasion of late has been, what do I do once I have the RoboHelp Server up and running. In other words, you have the server software installed, with all the elements communicating with each other, and you have your RoboHelp project all finished and waiting to be published. Now what?

The answer is areas. Areas are a new feature of RoboHelp Server in version 8. I have covered these in another post so I won’t repeat myself here. In order to publish your output you’ll need to have at least one area set-up on the server. There is a default area called “General” but in my opinion it is better to create your own. So how do you create one?

If you have access to the RH Server Web Administrator (see below) you’ll see a series of icons on the left. The top icon is used to create the users who will have access to the various areas. They are grouped. So the process is:

  1. Click Add next to the “Select a Group” field in the Users panel.
  2. Specify your group name (e.g. Department A) and click OK.
  3. Select your group in the “Select a Group” drop down.
  4. Enter a new user name in the “Add new User“ field and click Add.
  5. Click Yes in the resulting dialog and complete the username / password fields as required and click OK.
  6. Repeat steps 3 to 5 for other users.
  7. Click on the Areas icon (second one down).
  8. Click Add next to the “Select an Area” field.
  9. Specify an area name ensuring the “Protected” option is enabled.
  10. Next you need to add the group you specified in step 2 by clicking Add next to the “Add new Group” field.

That’s about it and you’ll find that area is available to specify in the WebHelp Pro single source layout properties in the RoboHelp client. You just specify the area and publish. Once published, the project is displayed in the Projects panel on the RH Server Web Administrator.

Migrating to RoboHelp 8 6th October 2009 (Tuesday)

Posted by Colum McAndrew in Adobe, RoboHelp.
Tags: , , , , , , ,
1 comment so far

My team has been using RoboHelp 8 in anger now in a production environment for a few months and have been blown away with its ease of use and functionality rich interface. Like any new application there are issues, but on the most part they are not significant and most have a reasonable workaround. We just evaluated things in the round before deciding that we could live with them. We’ve not had to change our procedures significantly. The only workload involved changing our style sheet, template and snippet usage together with the updating the associated style guide. That said, we didn’t need to change our style sheets and template but did so to accommodate functionality that had been implemented since the RoboHelp version we had upgraded from (X5).

We employed a slightly conservative approach deciding to have a new style sheet for use in our projects. This was a decision brought about by the new functionality centred about list and table styles. Particularly the use of multi-level lists makes our life so much easier when documenting procedural topics. Whilst we could have kept just the one style sheet, we have taken the opportunity to slightly change some of the legacy styles. This in itself is not a reason for maintaining two style sheets but inline styles are. We still have instances where inline styles (don’t get me started on these!) are prevalent. Our plan is to apply the new style sheet to all new topics and also to legacy topics that need amending, and leave the old style sheet on all other topics. As time becomes available we can devote time to migrating fully over to the new style sheet and delete the old one.

Our template (we only use one) contains a header, footer and topic title. The only issue we faced with it was that the footer appeared in the topic preview but not in the output. Eventually we discovered that this was down to a particular set of circumstances that are probably quite unique to us. Our footer is essentially a line provided by a style and a table with four cells. Each of these cells contained a hyperlinked image. As soon as we moved the hyperlinked images out of the table, all was well. This was hardly a deal breaker once we knew the cause and found a solution.

The only other real change was educating our authors in the use of multi-level lists. This works a bit like MS Word style functionality but as none of my team is that conversant with this, it took a session together to see how this should be used. The major issue was related to both a lack of understanding of style sheets over inline styles and the fairly complex structure of indented bullets. However once they saw how it is supposed to work they went away happy!

As we upgraded from X5, functionality that arrived in later versions has also been employed. Variables and especially snippets have been greeted with wild abandon! We have variables set-up for all our product names and components (some of which have a very annoying habit of changing two days before a product version launch) and snippets are in wide use for standard heading styles (e.g. “See also…”, “How do I…”, etc.). Finally the ability to have multiple topics open has allowed us to employ a dummy topic (with the relevant conditional build tag to ensure it is never output) that contains all manna of frequently used content that variables and snippets cannot handle (e.g. formatted tables). We just cut and paste them into the relevant topic. Simple!

If you are considering upgrading to RoboHelp from any version, there are numerous resources available to guide you through the process. I  have blogged about them here.

Celebrating online help in Windows 7 1st October 2009 (Thursday)

Posted by Colum McAndrew in RoboHelp.
Tags: ,
add a comment

A documenation release, Microsoft style! Click here to see how to do it but don’t forget your sick bag.

Me? Read Documentation? 30th September 2009 (Wednesday)

Posted by Colum McAndrew in Technical Writing.
Tags:
add a comment

I have just taken delivery of a new mobile (cell) phone. As is normal for me when I get any new toy I can’t wait to turn the thing on and play. Will I be reading the documentation? No! Not unless I have to ;-) Having said that, if I did, it wouldn’t take me long. The phone came with a getting started guide that amounted to a few pictures and a small manual of about 12 pages half of which is health and safety information.

It seems like if you want in depth information you have to look elsewhere. I did find a documentation directory buried deep down in the directory structure of the accompanying software CD. In there was a “full” user guide. I use inverted commas around “full” because it said correctly that you could synchronise data between PC and phone but nowhere told you how. It told you there was a wealth of applications and add-ons that could be downloaded without telling you where to look.

This sort of documentation is I’m afraid becoming more and more typical and the world is a darker place for it ;-(

RoboHelp Server 8 and the Table of Contents 29th September 2009 (Tuesday)

Posted by Colum McAndrew in Adobe, RoboHelp Server.
Tags: , ,
add a comment

Having implemented a RoboHelp Server 8 solution for the help files for one of our products, I am delighted to report that things have gone swimmingly. The installation of the server software went like a breeze, especially as both the server administrator and myself had no previous knowledge of Tomcat, and the publication of the help file output was as easy as falling off the log. Like anything new, there were teething problems and this post is about one of them. Take the image displayed below. Notice anything odd about it? Here’s a clue Look carefully at the Table of Contents.

rhserser_toc

In the Table of Contents the “Basic Tasks” book is clicked but the topic displayed is “Managing Tabs” which just happens to be located immediately above the selected book.  This problem is limited to WebHelp Pro output when viewed on the server either by clicking on the “View Project” button in the Web Administrator or displayed via the application. It does not occur if you manually open the start page in a web browser from the RH server. Neither does the problem manifest itself using WebHelp output. Apparently FlashHelp Pro output is not affected although I haven’t tested this.

Annoying? Yes, but there are workarounds. The bug is limited to books that do not have a topic linked to it in the book’s properties, so linking all books in your TOC to a topic is an easy way around it. This raises the following issues:

  • It would be sensible to link each book to the first topic in the book so as not to confuse the user. In the above example, the “Getting Started” book would be linked to the “Logging onto the Application” topic, the“Basic Tasks” book would be linked to the “Finding and Opening an Experiment” topic, etc. However if a topic is ever added to a book in the first position you would have to remember to change the book’s properties to change the link.
  • Some have got around this issue by adding an overview topic to each book. As such the overview topic will always be the first topic and so the book’s properties will never require changing. The drawback here is that the overview topic may be little more than a sentence followed by a bulleted list of hyperlinks to other topics. This may not fit in with your style guide or vision of a useful help system.
  • A third way around the problem is via the use of a redirect topic. The theory behind redirect topics is described in Rick Stones Tips n Tricks file, but basically it does exactly as it says on the tin. A topic is opened and redirects you to another topic. This would work in a similar way to lining a topic to the book’s properties but has the advantage that the topic is not linked to a book AND displayed in the Table of Contents. It is generally accepted not to be good practice to have a topic in the Table of Contents twice. Whilst the effects of doing so are mitigated by having the two Table of Content references beside each other I would still ere on the side of caution. The problem with redirects is that it requires the user to be comfortable with editing the topic HTML. This is not something to be considered likely as getting things wrong can cause untold problems. However if you are comfortable with this approach, this is my preferred option.

In summary, this bug is annoying and fairly difficult to track down. However it is not the end of the world. Hopefully this article has explained the problem so you don’t have to go looking for it, and proposes a number of solutions to alleviate it. As an aside, anyone affected by this is encouraged to report this to Adobe.

Security and RoboHelp Server 8 21st September 2009 (Monday)

Posted by Colum McAndrew in Adobe, RoboHelp Server.
Tags: ,
add a comment

There is something about the phrase “security risk” that sends web users into a state of apoplexy. In these days of firewalls, security is king and anything or anyone that upsets the status quo is to be defiled and ridiculed. But is that justified?

The recent announcement by Adobe that they had uncovered a security risk in RoboHelp Server 8 had the above effect in some circles. Talk of abandoning RoboHelp Server, and even RoboHelp, was apparent. Perhaps IT Directors saw this announcement as a threat not only to their server security but also to their jobs. I guess this is justified as if there ever was any exposure it would be their butt on the line.

As a Technical Writer at a company that has implemented a RoboHelp Server 8 solution, and where security of one’s intellectual property is of paramount important, I guess such an attitude is justified. My team and me have had to build a series of hoops and then jump through them in order to get the documentation into a production environment. This includes displaying the documentation in a secure browser and with an application that uses basic authentication to pass (unbeknown to the end user) a userid and password to display it. The basic premise being that if you don’t have access an application licence you won’t get access to the documentation.

It may be a complicated set-up but it makes it harder to hack into our intellectual property. Not impossible mind you, and therein lies the point I’m trying to make. If I was the IT Director at GCHQ or the Pentagon it is fair to say that security would be your number one concern. Organisations like GCHQ and the Pentagon are in the frontline by being who they are. They are rightly doing whatever has to be done to make a hackers job harder. However the recent case where an English student was extradited to the US after he hacked into the Pentagon computer shows that there is no such thing as total security. Make it difficult if you wish but someone, somewhere will see it as a challenge to undermine it.

If a hacker made public the secrets of GCHQ or the Pentagon it could have implications for world peace. If a competitor were to compile a product that duplicated our functionality it could prove disastrous to our company. Different scenarios but you can bet our Managing Director would react in the same way as the head of GCHQ or the Pentagon. We may not have to implement the same anti-hacker solutions but the end result amounts to much the same thing.

Perversely the security risk in RoboHelp Server 8 wouldn’t matter in our implemented solution as it only affects unauthenticated users. We also deploy the documentation on a server solely dedicated to the help files. If someone were to hack into it, they’d still have to code the application. Impossible? No, but difficult, expensive and outside the scope of all but the most determined? Definitely! Mind you, we have implemented the update (see below) already just in case.

Postscript: Thankfully the hole in RoboHelp Server 8 application was plugged quickly with the announcement of an update. It requires you to stop the Tomcat server, make backups of some important files, apply the update and restart the Tomcat server.

Adobe and Omniture 15th September 2009 (Tuesday)

Posted by Colum McAndrew in Adobe.
Tags: ,
add a comment

Breaking news from Adobe. It is acquiring Omniture. According to the Adobe website, the acquisition “Furthers its mission to revolutionize the way the world engages with ideas and information. By combining Adobe’s content creation tools and ubiquitous clients with Omniture’s Web analytics, measurement and optimization technologies, Adobe will be well positioned to deliver solutions that can transform the future of engaging experiences and e-commerce across all digital content, platforms and devices.” Why did it all break just as I was thinking I’d go to bed? Now I’ll have to stay up longer to find out more!

Documentation versus social networking 15th September 2009 (Tuesday)

Posted by Colum McAndrew in Acrobat Professional, Adobe, Captivate, FrameMaker, RoboHelp, Technical Communication Suite, Technical Writing.
Tags: , , , , ,
7 comments

As someone who uses social networking in a limited and more focused fashion than most, I was interested in a entry called “Social Web for Documentation” on CherryLeafs’ blog. It features Ellis Pratt interviewing Anne Gentle. In it Anne uncovers how social networking sites can be used to provide a level of user assistance and how changes in the way users interact with documentation means we Technical Writers may need to adapt. It also uncovers some of the potential pitfalls of using these new media. Altogether an interesting 10-15 minutes.

If I’m honest, I have until recently looked on from the sidelines when it comes to using social networking professionally mainly because I failed to see a use for it. After all a recent survey revealed that 40% of tweets were meaningless cyber babble of little use to a wider audience. All that changed last March when I saw an example of how it can influence and educate others. I was at a conference for a national charity I am involved with where it was demonstrated how a campaign message had been widely disseminated throughout the media. Supporters had been asked to tweet on it at the same date and time. The success of the action was unprecedented and achieved the desired aim.

Like most things in life, the key is ensuring a strong focus and key deliverable. A good example of this is Adobe’s Senior Product Evangelist R J Jacquez. If you use any Adobe product as part of the Technical Communications Suite or RoboHelp, Captivate, FrameMaker, Photoshop individually, and don’t follow him on Twitter, you need your head examined. His tweets are a classic example of how social networking can be used to add value to the user documentation experience. If you don’t use Adobe products, you should still follow him (even briefly) to get an idea of how it could work for you.

I suppose the purists could argue that using social networking site in this manner is more marketing than documentation. There is more than an element of truth in this but does that matter? Isn’t it more grist to the mill? In the modern business world we are all busy people and will use whatever method is available or easily to hand to find out what we need. This could be Google, LinkedIn, Twitter, web based help files, local help files or a printed document. A documentation strategy that includes web based movies, help files on a PC hard drive and peer to peer product forums is perfectly acceptable. So is a wiki with links to other resources. But what really adds value is the ability to tie all these elements together. For example links to associated articles, product news or requesting feedback. All are just a few of the uses of social networking and as Technical Writers can often work inside a corporate bubble with little user contact, this has to be encouraged.

In my opinion, one of the most interesting advances in recent years has been the Googleisation of user help experience. Whether this is good or bad, the fact remains that millions of people go to Google first when searching the internet. Whilst a good help file or document index is still necessary, the inexorable move towards searching for keywords must not be ignored, particularly when directing documentation to a younger, web savvy audience. What is more, the search algorithm deployed by Google (and other search engines) is more likely to display blogs and wikis above other articles. If that doesn’t help make up your mind, I don’t know what will!