10

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.

Improve this question
3
  • Why not a web site/wiki?
    – Mike Chale
    Commented Sep 7, 2012 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
    Commented Sep 7, 2012 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
    Commented Sep 7, 2012 at 18:57

3 Answers 3

Reset to default
9

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.

Improve this answer
9

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.
Improve this answer
1
  • 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
    Commented Oct 30, 2012 at 15:29
6

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.

Improve this answer

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .