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.
I think it is important to make a distinction between the ease of use of the
knowledgebase system itself and the suitability of the content for
presentation in that format. One of the key points of my Every Page is Page
One idea is that we have to write content so that it works in a search-based
environment. Unfortunately, most of the content that gets put in
knowledgebase systems is not written to work well in a search-based
environment. It does consolidate the material that serves a particular user
purpose, it does not establish its context well, so that it is easy to
identify the right article in search results, and it does not link richly to
related topics to allow users to navigate the last mile.
One example I like to give is of a company that makes backup software. They
were having problems with people finding information in their knowledgebase.
I did the most obvious search possible for such software: "<product>
restore". On Google, that led to a forum post in which a user complained
bitterly that it was impossible to find information on restoring in the
docs. When I did that search on the docs themselves, the first dozen results
were puff pages that said that you could backup and restore but didn't say
how. The thirteenth or so was the actual restore procedure.
So the problems here are:
1. There were too many puff pieces obscuring useful information
2. None of the statements that said you could restore were linked to the
procedure for doing a restore.
This second point should be elementary for all product documentation in the
hypertext age. You should never, ever, mention a system function or
procedure without linking to that procedure. If every mention of a procedure
linked to the documentation of that procedure, then people looking for that
information in docs or a KB would be able to find it with one click no
matter which topic the search engine returned as the first result.
In the end, help systems, KBs, CMSs, and the plain old web are just
hypertext systems, and no hypertext system works well if the content it
contains is not actual hypertext. (And most of them work pretty much just as
well as another if their content is real hypertext.)
Mark
-----Original Message-----
From: techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf
Of Robart, Kay
Sent: Thursday, September 29, 2016 11:29 AM
To: John G <john -at- garisons -dot- com>; Suzette Leeming <suzette -dot- leeming -at- gmail -dot- com>
Cc: TechWriter <TECHWR-L -at- lists -dot- techwr-l -dot- com>
Subject: RE: Online help access question
It sounds like they're talking about a knowledge base. I have no opinion on
the proprietary information/intellectual property angle, although I would
point out that most companies that have a knowledge base require a password
to access some or all of the content, even Microsoft.
My wider comment as a user of software that has gone from delivering Help to
a knowledge base is that I find the knowledge base much harder to use for
locating specific information. You almost always get far more search results
than you need or even can comb through. I have often been looking for a
particular piece of information, maybe for something that I just forgot how
to do in software that I am otherwise familiar with, only to be deluged by
thousands of search results. Many times, this has resulted in my not finding
the answer I needed and having to comb through the software myself to try to
remind myself how that thing worked. Sometimes the knowledge base is more
useful, particularly when you have an unusual problem you're trying to solve
and other people can contribute solutions, but most of the time, it's more
confusing and difficult to use.
Kay
On Thu, Sep 29, 2016 at 9:32 AM, Suzette Leeming <suzette -dot- leeming -at- gmail -dot- com>
wrote:
> I'm looking for opinions and/or examples. Here's my situation:
>
> I create browser based help for a suite of financial applications,
> generally used by banks, credit unions, etc. A suggestion has been
> made that we put all of our documentation online, wide open for
> everyone who wants to access. I disagree, since I feel it contains
> proprietary information and represents intellectual property. Our
> competitors could very well look at it and say "we can do that
> better", or use information they see there against us when competing for
the same business.
>
> We're not the same as Microsoft Office or even Sage Accounting (which
> were examples given to me) because we are not dealing with retail, off
> the shelf applications; ours is enterprise software in a highly
competitive industry.
>
> My proposal is to restrict access somehow, perhaps requiring user
> accounts, or verified IP addresses, etc. I note that none of our
> competitors make their documentation freely accessible.
>
> Have any of you come up against a similar situation or have any
> thoughts/ideas on how I can best present my case?
>
> Suzette Leeming
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy
> and content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as vwritert -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
>http://www.techwhirl.com/email-discussion-groups/ for more resources
> and info.
>
> Looking for articles on Technical Communications? Head over to our
> online magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our
> public email archives @ http://techwr-l.com/archives
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and
content development | http://techwhirl.com
Looking for articles on Technical Communications? Head over to our online
magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public
email archives @ http://techwr-l.com/archives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and
content development | http://techwhirl.com
Looking for articles on Technical Communications? Head over to our online
magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public
email archives @ http://techwr-l.com/archives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
