25

I write training manuals for a software product. When that product is next released one of the tools in it will be marked "in beta". i.e. that functionality is is included only as a technical preview.

Product documentation will surely include that functionality, but should a training manual? The functionality will vastly improve the user experience, but is obviously liable to change and updates.

So is it best practice to train users to use a tool that is still in beta, or just ignore it altogether regardless of how useful it is?

Improve this question
3
  • I would say this largely depends on your product's release cycle. If the 'final' version of the feature will ship in, say, a month, updating the training might be too costly. But of the users will have to wait a year for the final version, they are likely to start getting used to the beta anyway.
    – user23425
    Jan 23, 2018 at 18:19
  • Are you talking about flagging something down as beta?
    – tuskiomi
    Jan 23, 2018 at 22:56
  • Thank you for all your answers everyone. I think there's general agreement that we shouldn't train on changeable functionality for the main part, but add an appendix to the manual. I really like that idea and it fits in nicely. I think I will go with that. What makes it complicated for us is that we aren't sure when it will come out of beta - it could be 2 months, it could be a year. Anyway, thanks again, even if I didn't pick your answer as most helpful!
    – Mark Ireland
    Jan 24, 2018 at 16:10

9 Answers 9

Reset to default
14

I usually include a clearly marked "Beta Features" section. (either overall bundled together, or in individual sections marked as "BETA only").

This allows non-BETA users to skip it, and eliminates people complaining about the absence of BETA features in PROD version.

Then, put less effort into BETA section if you intend to change it early and often (as the product updates fast and documentation updates just as fast), OR, more effort if you anticipate slower rate of changes.

Improve this answer
1
  • 1
    +1 - One should usually document early (with caveats) rather than leave gaps. Famously GMail remained in beta for five years - imagine what would happen if a somewhat stable function remained undocumented just because the company bureaucracy hadn't moved on from a beta label
    – Jason Fox
    Jan 23, 2018 at 22:14
14

This is dependent upon how likely you are to publish a new training manual when the feature leaves beta.

If you are regularly updating your training materials, so that any changes to the beta feature come with an updated manual, and your users use the updated manuals, then there is little harm in pointing users towards features that are helpful, provided that it is made extremely clear that the feature is currently in beta.

If it is likely that updated manuals won't be made available to your users it's best to keep references to features that are likely to change out of the training literature until they have been finalized.

If the feature is extremely beneficial you can always point to it at the end of the manual, along with links to more thorough documentation, as additional reading.

If the beta feature is complex enough to require dedicated instruction then it might be a good idea to publish a separate document that is the beta training document for the feature. This will provide instruction and get feedback on how best to instruct users in it's use before incorporating the feature into the regular training.

Improve this answer
2

I suggest you resist the urge to train customers in beta functionality unless they are specifically participating in your beta. Base your standard training on released versions only.

That is not to say you cannot create the training content, just don't include in the final deliverables yet. If you are using a single sourcing solution you can accomplish this various ways.

You may want to take advantage of having those trainees around and invite them to test new features but it should be clear to them that this activity is different from the regular training. This assumes onsite training, don't spring this into a webinar or you risk blurring the lines.

Improve this answer
1
  • 1
    "...or you risk blurring the lines" This seems to be crucial here. A clear demarcation of what is final functionality and what is beta is really, really important.
    – hBy2Py
    Jan 23, 2018 at 18:15
2

I'd say look at this from the customer's point of view. If they are likely to run into this functionality while doing the training, they desire that feature, and possibly may get aggravated if they don't see that feature in the training manual, then I would definitely add it.

I like @sphenning's idea of having info about the functionality at the end of the training doc. Maybe a one line mention in the main content with a link to the content at the end. This may make it easier to update for you, and also emphasize to the user that it's beta.

Improve this answer
1

In a situation like this, my first instinct is to consult with my product manager, to ensure that he or she is OK with pointing out features like this. Because the feature's going to be generally available, I'd choose to add it to all docs.

Improve this answer
1

If you add it at all, add it as an appendix.

An appendix to the main manual indicates that it is not a full part of the product.

Also, if the beta functionality makes it into the main product, you can move the section into the main manual. While if it is removed from the product, you delete the appendix with no effect on the main manual.

Improve this answer
0

I'd say you create a draft version of the document with Beta features included but marked with something to indicate that it's a beta feature. Then the doc can be distributed with the beta software.

Once a new production release is locked in, you can then easily go through your draft version, searching for each beta feature to:

  1. remove the beta symbols for those features that moved to production unchanged
  2. update the docs for any features with changes made during beta testing
  3. remove any features that failed to make it from beta to production

By starting the work while still in beta, you can speed the transition to a new production document version, but you are still highlighting the fact that features are not necessarily going to make it into production by the end.

Improve this answer
0

Beta features should be mentioned only in beta docs, which should be clearly labeled as such.

Training materials should reflect whatever version is used in the training. If the training is for a release version, you might include a "preview of coming attractions" module to cover things in a beta version, but Google "forward-looking statements" first.

Improve this answer
0

I would keep a universal training manual for all types of end users to avoid worrying about a maintaining separate content for beta and non-beta users when your product goes live and no more beta. Beta features, however should be highlighted in other types of user communications, such as what's new or release notes.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.