Genii Weblog

CoexLinks needs a new kind of documentation

Wed 22 Mar 2006, 01:53 PM



by Ben Langhinrichs
As I was working on the documentation for CoexLinks 2.6 (which should be available on our website later today, or early tomorrow) over the past several days, I realized that we need to rethink the documentation.  I don't mean rethink whether it is a Notes database or a Word document or a PDF document, but the basic structure of how we organize the growing number of options.  When CoexLinks 1.0 was released in April, 2003, there were only a few options available, but as more companies have started using CoexLinks as part of their coexistence strategy, there have been more nuances, features, desired restrictions, etc. etc.  Mind you, it is still simple to configure and use for the average administrator, but aside from the three options that practically everybody uses, COEXDoclinkType, COEXPrependDocLink, COEXPrependDocLinkText, there are twenty one other possible options, and some can have a fairly major impact on how CoexLinks operates.  That is starting to be enough to confuse people, and it is certainly enough to make it possible that people might start missing out on important functionality which they could use if they knew about it.

But what is the best way to address this?  The twenty four options are documented in the CoexLinks User Manual, but even if somebody were willing to read through them all, it is not always easy to absorb the importance of one or another option, and it is even harder to understand how some interact with each other.

1) Categorization: My first thought was to split the options up into groups or categories, which should certainly be done if nothing else is.  Options such as COEXExcludeHintServer, COEXIncludeHintServer, COEXExcludedLinkText, COEXExcludedDocLinkPreserve and COEXIncludeReplicaID are all closely related, so they should be grouped together, but what of COEXLimitToDB? It could easily be used together with those, but it could also be used for completely different purposes.  Should an option be contained in multiple categories?

2) Scenario Solutions: Mark Ramos, whose Granite Software provides support and also sells CoexLinks along with Genii, suggested scenario based documentation.  It would be possible to describe various scenarios that most companies who use CoexLinks face, and the options they would use to help face that scenario could be explained together.  That seems like a good plan.  I am not sure what to do about the companies who fall between the scenarios or who have overlapping scenarios, but I guess they could recognize themselves in more than one place.  I am working on coming up with scenarios now.
 
3) Wizard configurator:  Mark and I also discussed some sort of a wizard that would help people through the process.  This could be an automated wizard or even just a paper based wizard, but a series of question would help establish which options make sense for your company.  One advantage to this approach is that if a new problem appears, you can go to that problem solving item and find the option, rather than having to re-envision the scenario.  For example: 
 
Issue: Doclinks that are simply pointing back to the e-mail responded to are becoming attachments and confusing people.  They were easy to ignore as doclinks, but not as attachments, and the user can never really access them as they go back to a different user's mailbox.  
 
Solution: Use COEXExcludeHintServer statements to exclude each of your mail servers, as that is where these doclinks will point back.  If you have specific database that should be on the mail servers and render doclinks, use COEXIncludeReplicaID statements to allow those doclinks to be included while others from the mail server is skipped.
 
So, does one of these seem best?  If I do all three, will it just make the documentation bigger and more cumbersome.  Any thoughts?
 

Copyright © 2006 Genii Software Ltd.

What has been said:

No documents found