2

Question

What approach should be taken when designing end-user documentation for a large/corporate (web-based) software system? Is there industry best-practice that combines good UX with maintainability?

I'm hoping for an answer that focusses on advice for how documentation should be organised and how it should be distributed.

I realise this is a possible duplicate of https://stackoverflow.com/questions/663728/how-do-you-approach-documentation-external-not-in-code-documentation, although that question is primarily related to documentation for an in-house system, or development documentation, rather than customer-facing/user-facing documentation.

Background

I'm doing a review on documentation for a software system. I put web-based in brackets above, because it may or may not impact on the answer... Currently the documentation is a mess of large PDF files and I'm fairly sure none of our users read them. I believe that having bad documentation causes us extra support.

I believe my end result needs the following (although the question partly covers whether this is correct):

  • User documentation that provides help on what features are available and how they work.
  • Admin documentation on how to setup the system for first-time use and how the administrative features work (e.g. user/record maintenance).
  • An installation guide, because it has several components (some of which are optional) and there is no automated installer.

The system is updated on a reasonably regular basis with new features, and the documentation needs to reflect the changes to existing features, or detail any new features.

I'm currently considering web-based documentation for the user and administrator guides - i.e. something like a wiki (but read-only), which is searchable and can easily be added to.

I've found the following question on SE that suggests it's possible to export a wiki to a read-only HTML format: https://webapps.stackexchange.com/questions/23143/how-to-export-all-pages-from-mediawiki-to-hierarchy-of-html-files, but I still need to do more research into different types of wiki and the export tools available... Also, if the export tools don't produce a user-friendly result, the whole exercise is pointless.

  • Evernote is certainly an option I would consider. You have great flexibility to decide the rigidity and structure of your IA, is very simple to maintain/edit by anyone, and is managable on mobile. Great search functionality as well. – ewittke Mar 6 '14 at 17:19
  • Reading through your post again, this solution is best for smaller teams rather than large corporate systems. – ewittke Mar 6 '14 at 17:21
  • This is really a technical writing question, which is a field unto itself. Alas, I don't think we have a tech writing SE site... – DA01 Mar 6 '14 at 18:14
  • Thanks @DA01, I was wary of posting this question here, as it didn't seem a 100% match for UX.SE. But I'm after documentation that is easy to read and search, which is all UX :) – oliver-clare Mar 7 '14 at 8:49
3

I would actually suggest you set up WordPress or Joomla. Although not its normal use it will allow you to update information quickly and easily.

  • Updates to the UI can be made easily and apply to all immediately
  • You could restrict via password access and have different levels
  • You could use this as a intranet system only, or allow it to be accessed from where ever
  • It is very easy to set up searches and tag based systems
  • Support ticket systems can easily be supported
  • The system can easily be backed up, maintained and data can be exported very easily in to future systems

I know this doesn't fully answer your questions but it seams as though thinking outside the box here could help you out.

  • 1
    I hadn't thought of using blogging software, but the benefits you've highlighted to this approach do match up to the kind of thing I'm after. – oliver-clare Mar 7 '14 at 8:48
0

I agree with Tim.

Additionally, you can create this as part of an Intranet that can be updated and maintained on the go. You can structure it like an FAQ or Knowledge-base with a predictive search.

Microsoft does this as well.

enter image description here

0

I believe using a wiki is a great way to organize and distribute documentation, as it let's people contribute and give readers the opportunity to provide feedback. My favorite solution would be Atlassian's Confluence wiki. It is a great tool for documentation, because it comes with great collaboration features and there are a range of add-ons that help managing and publishing the documentation.

  • I am using Atlassian's Confluence wiki and I am missing the capability to add numbers on top of the wireframe, so that if I want to refer to a specific part of the UI, I can place a small circle with number on the wireframe image and place an explanation with the same number on the side. another problem is that I have to use screen shoots to show my screens and every time there is a small change I need to export all of them again, I would prefer to use a link. – Eran Bar Feb 1 '18 at 14:02

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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