Take the 2-minute tour ×
Salesforce Stack Exchange is a question and answer site for Salesforce administrators, implementation experts, developers and anybody in-between. It's 100% free, no registration required.

We're preparing to release a package on AppExchange, and we're starting on the documentation (Getting Started Guide, API Reference) for it. The Developing App Documentation section of the ISVforce Guide doesn't provide much guidance.

I'm wondering about the recommended way to release documentation with a package. Should we just include it in the AppExchange listing?

It's not really "configuration" instructions, but I wondered whether we should include some documentation in the package and link to it with the "Configure Custom Link" option in the package.

I realized that we could include a tab, Visualforce pages, and even static resources with the package, but I'm not sure whether that's the right direction.

We're documenting custom objects, Apex classes (with an API that developers may want to access) and Visualforce pages.

share|improve this question
    
Why not a web site/wiki? –  Mike Chale Sep 7 '12 at 1:02
    
@MikeChale: Where should we place the link to that site? Is the AppExchange listing sufficient, or are there other places to include it? –  tomlogic Sep 7 '12 at 17:46
    
The AppExchange would be sufficient. On one random listing, I see under Support a link to the vendor's knowledge base. –  Mike Chale Sep 7 '12 at 18:57
add comment

3 Answers

up vote 8 down vote accepted

Assuming your application uses at least one custom tab, I would leverage the 'splash page' functionality of custom tabs to display a landing page on your website, with appropriate links off to docmentation, FAQs and the like. A bonus with having documentation elsewhere means you do not need to roll out a new version of your package just to update the documentation for it.

You could make that particular tab the default tab for your application, meaning that people are going to see it when they first use your app, and then also make sure that it's readily accessible from elsewhere too.

share|improve this answer
add comment

Absolutely do NOT include your documentation in the package itself. Here's why: Chances are your documentation team is not (or will not) be the same people as your developers. Your need to update the documentation will not be on the same schedule as your software release schedule.

Including documentation in the package ties the two together. I mean, do you really want to have to push a software patch to fix a documentation typo?

Whether you include it in the AppExchange listing, use Solutions or a knowledge base or external web site, or iFrame the content into a VisualForce page, the content should be external to the package itself.

As you choose your approach (and any of those approaches are reasonable - plus there are probably others I haven't considered), keep two other factors in mind:

  • Remember you can include a help link on your VisualForce pages (if you have any).
  • Remember that you may want to support multilingual help at some point.
share|improve this answer
    
Great advise. In terms of having an iFrame on your VF page, make sure to mention that it's just for displaying help text during any subsequent security reviews. Otherwise they'll probably ask about it for security reasons. –  Adam Oct 30 '12 at 15:29
add comment

I think online documentation is the best; it allows you to keep it up to date and easily version it, if necessary. I see some AppExchange listings provide links to their knowledge bases on the app's Details page. That seems perfectly reasonable and user-friendly to me.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.