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.
Sarah Blake asked
"I've just moved to a new gig, and they have a product setup where the
'product' is the platform, plus a number of optional and mutually
independent modules that are 'switched on' according to the license."
If there are a set number of standard configurations, especially if they
are named products, a DITA map solution might work. You'd have a different
map file for each configuration, and you could output to both PDF and HTML.
For topics shared across maps, you'd use conditional text based on the
configuration. All the outputs would exist in a central repository, and the
relevant outputs would be shown in each configuration.
So you'd have the basic map file that outputs sections 1-5. Then, when a
new module is switched on, *something* is tripped in the software that
calls the outputs that include sections 1-6.
Often, though, there's a desire to include information about optional
modules, in the interest of promotion, etc. But nothing is ever easy.
Chris
On Fri, Jan 11, 2013 at 9:21 AM, McLauchlan, Kevin <
Kevin -dot- McLauchlan -at- safenet-inc -dot- com> wrote:
> I look at it this way:
>
> If the actual "product" that a customer buys is the platform, plus
> one-or-two modules, and there are 50 or 100 modules to choose from, then
> yes, giving them a document with instruction and description for all
> modules might be intimidating and confusing. They wouldn't need 90 percent
> of the doc. You might need to generate specific docs for each sale, or you
> might need to have a comprehensive BoM set that CAUSES the platform doc
> plus JUST the relevant module docs to be assembled Is this printed or PDF
> or Help? It will make a difference in how you weight this decision.
>
> On the other hand, if the platform itself does a lot of actual,
> customer-facing, customer-usable operations AND it is common to add one or
> two (or five...) modules, from a selection of perhaps a dozen, AND they
> all have some common ground, THEN I'd just document everything in one
> place, keeping the modular stuff..... modular. If you have this-or-that
> module, you read the general platform chapters/topics, and you also read
> the module chapters/topics for the specific modules that you've purchased,
> and you can ignore the others. How many people have died, or how much
> business has been lost because GM Owner's Manuals contain the base model
> info, plus the LS, LT, LTZ, and other model features, as well as
> descriptions of optional equipment?
>
> This assumes that the modules are relatively self-contained and that you
> don't need to include a lot of spaghetti to account for interaction and
> interdependencies. If the latter is the case, then you'd serve the customer
> well by writing your "module" chapters/topics more about functional groups
> and clumps of product modules that are normally purchased and used in
> concert. Similarly, if some modules are ... um... grander than others,
> such that you purchase one important module, and you have the option to
> purchase additional modules that extend the function of just that original
> module (i.e., constrained modules that aren't useful independent of the big
> module) then that product structure would tend to dictate your document
> structure. Clumps that go together in that fashion should be documented in
> one place, regardless whether every module in the clump will be purchased
> by every customer.
>
> ON THE THIRD HAND (the Gripping Hand?) if your documents are not printed
> (by your company) but are electronic-only, then no significant cost is
> incurred to ship extra electrons, and any documentation modules that did
> not apply to the customer's current version of the product could be
> considered passive up-sell for additional features of your product that
> they might want in future. The modules they don't use now might give them
> ideas for future expansion. Those will remain in the back of their customer
> minds and will be visible every time a customer sees the ToC. If they want
> to print out instructions, they can select just the parts that apply to
> them. Discuss with the PLM.
>
>
>
> -----Original Message-----
> From: Sarah Blake
> Sent: January-11-13 8:25 AM
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Modular products...
>
> ...this has got to be a solved problem by now, right?
>
> I've just moved to a new gig, and they have a product setup where the
> 'product' is the platform, plus a number of optional and mutually
> independent modules that are 'switched on' according to the license.
>
> I don't want to confuse the users with documentation for modules they
> don't have access to, and I don't want to have to manually generate
> tailored documentation for every sale. Has anyone successfully used other
> options?
>
> (Yes, I know I asked this same question like six years ago. I didn't
> manage to figure out a good, scalable solution then either)
>
> Sarah Blake
> Technical Writer
> Arieso Ltd
> Office +44 (0) 1635 232470 | Fax +44 (0) 1635 232471 | Email
> sarah -dot- blake -at- arieso -dot- com<mailto:sarah -dot- blake -at- arieso -dot- com> | Web
> www.arieso.com<http://www.arieso.com/> |
>
>
> The information contained in this electronic mail transmission
> may be privileged and confidential, and therefore, protected
> from disclosure. If you have received this communication in
> error, please notify us immediately by replying to this
> message and deleting it from your computer without copying
> or disclosing it.
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Writer Tip: Create 10 different outputs with Doc-To-Help -- including
> Mobile and EPUB.
>
> Read all about them: http://bit.ly/doc-to-help-10-outputs
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as kafkascampi -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
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Writer Tip: Create 10 different outputs with Doc-To-Help -- including Mobile and EPUB.
