I'm involved in a massive project that is turning 70+ antiquated systems into one system for a large company. The whole team and the executives at the company realize that this is a huge undertaking and that some things will be different for many people and there is no way around it. I'm one of the 5 UX/Information Architects on the project and just the other day I realized that we're going to need help documentation and a help interface.

Right now everything is in flux. Since there are so many systems there is no current-state understanding of the entire system and how everything connects. As we develop requirements and document the functionality that the new system needs to have we start finding more functional requirements that we didn't know about.

I really can't fully state how big this application will be for this company. As a result I can see right now that help will be crucial when we transition over to the new application, but I don't know when we should start working on the help documentation. I really don't want to wait until the application is finished or close to finished because I know the majority of the project team will sweep it under the rug and say that training will cover it.

Basically, my question is when should we start collecting help documentation, and what is the best way to document it as the project progresses?

3 Answers 3



If you are working on a managed project, there should be Design Requirements, which should give you a foundation to build from. During development there is much in transition, but approved design documents can assist in creating help info.

The final stages of system testing and user acceptance testing, should give you the chance to fine tune your help documents. If they are mostly complete prior to testing, they will be extremely helpful to testers, which will make their job easier, while testing your help pages at the same time.


As soon as there is anything at all that you can say -- so, if not now, then very soon. "Anything at all" can leave place-holders for specific interfaces if they haven't been worked out yet; you can probably at least start writing your conceptual documentation ("what is a..." for the key things in your application), and you probably have some ideas about workflows that imply an outline.

The danger of waiting until the end is not just that it will get short shrift. In every sizable documentation project that I have worked on (and I've been doing this for a couple decades), the process of trying to explain it has turned up problems in the interface. The sooner you flush those out, the more likely it is that they'll get fixed. This is especially true on a project with a large team where no single person has a consistent view of the entire system. Each person works on his piece and you only find out later that they don't quite line up; documentation and test plans are the remedies for that.


The goal of a UX process should be to create an interface that won't need help at all. It'd be so naturally intuitive and meet the desires and needs of the end-user that it'd be moot.

Of course, that's rarely a reality we have the pleasure of accommodating.

As such, sometimes a means to provide help is a necessity. As to when to start working on it, I think James is close with 'now' but I'd probably go with '2 months ago'. ;)

Point being that this has to be part of the process. UI design, content, requirements, help, etc. all need to be developed in conjunction as they all influence each other.

As a bonus, as help is being created, it may provide opportunities to discover ways to circumvent the need for the help that is written through updates in the UI.

Your Answer

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

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