Welcome to TechWhirl Forums

Sign in or Register to get involved in our discussions.


Depth of Documentation in a LIMS User Manual

Hello everyone,

I have a question and I need the advice of veteran tech writers.

I'm starting to write a reference-based user manual for a quite large LIMS application. And there are actually many fields in each screen some of which are very obvious (Date of birth). Do I need to document ever single field & its use despite how obvious it is. or should I only document the fields that are new or different based on the audience's general knowledge?

I was thinking of creating a section where I collect all the common fields that are found throughout the system to avoid needing to constantly describe obvious terms, would that be better or not for a user manual.

Thank a lot for the help!

A

Comments

  • AMosesAMoses United KingdomPosts: 4

    Hello Ahmad,

    I'm not sure I'd call myself a veteran tech writer (far from it), but I have asked myself the same question that you have.

    I usually document every field that is available. This is a) for completeness, and b) to avoid that a user needs to navigate away from the page to the area where the "common" fields are listed.

    Depending on the format that you're writing in, you could save yourself time by creating a chunk that contains the common fields, and reference that chunk wherever it's needed. For example, in FrameMaker you can use a text inset, or in DITA, you can conref that chunk. This also has the advantage on saving localization cost, because that same text only needs to be translated once (obviously, this only works if the fields are translated consistently in the UI).

    I'd be interested though how other writers view this.

    Hope this helps.

    Anne 

  • Thanks a lot for your feedback!

    I totally agree with your idea about completeness. Yet at the same time I feel that in a way I am treating the readers like buffoons who can't figure out these basic fields while including the fact that when deadlines are super-tight you tend to feel that they are more like time-wasters.

  • KarenGKarenG Posts: 1
    I struggle with the same thing. I've sided with not documenting the obvious. That said, you must ask, "what is obvious?" You need to know your audience and your product. Writing for a specialized product actually makes that easier, because your audience isn't as broad as say, users of Microsoft products. So you might be able to safely presume they understand that, in the context of defining a new person record, the Date of Birth field is that person's birth date. Is there anything important (of value) you need to add? Maybe the format (mm/dd/yyyy)? Otherwise, omit a description.

    Another thing I've struggled with is whether to provide a full list of fields found on a page. For setup or administration documentation, I typically do. Even if I don't describe each field, I still list them. You never know when someone might be reading the doc and not looking at the software. It could also be helpful to know ahead of time the items they might need before starting to do something (especially if information is required).

    Lastly, you also need to consider online help. In one of the systems I'm documenting, if I provide online help for a field, there's a help icon next to the field label. Image the page if I put in help for every single field! So I really do try to limit the help to useful information.

    Hope that helps (a year later!)
  • AprilApril Posts: 3
    Hi Ahmad,
    I had the same question as you years ago, and also had some discussions with colleagues.
    Here are some ideas might help you a bit:
    1) Is it possible to change the format of help? Typically an online help with embedded assistance is the best choice for GUI users. In that way, you don't need to describe any "obvious" things in the help topics for sure, and even can leave out those are not so obvious if the embedded assistance is able to serve.

    2) If you have to stick with a manual. It would be good to consider that nowadays most users hate "Reading the **** Document". So creating a minimalism manual would be the better way to go. That is to say, focus on the user tasks, leave out the noise (those are too obvious and/or not highly relevant to the task).

    3) It is important to understand/clarify the positioning, scope and the audience of your manuals. if possible, try to have a user and task analysis to figure out what to deliver to the whom. Yeah, pretty challenging with kinds of limitations and constraints. we can have a way much wider discussion on this...

    Br, April
Sign In or Register to comment.