I’m developing a program for a group of scientists. The requirements are that user input will be given in the form of an XML configuration file. Also the requirements state that an XSD file will be used to specify the structure of the XML file. The scientists have domain specific knowledge and usually have some (often incorrect) knowledge of computer programming. If the user enters: 1) an XML file that is not properly formatted in general 2) does not comply with the XSD file; what should the error message say? Right now I have
1) Missing XML config file
2) XML config file is not properly formatted
3) XML config does not match structure in XSD
Is there a clearer way to express the above?

  • Option 3 is closest to the idea of suggesting the next step, but you can be more specific. (Can you give a line number, or a word on a line where the parsing fails?) As for exact wording, that's a question for a technical communicator. If you're not sure the wording works, test your phrase on people in your target audience. – JeromeR Jul 24 '15 at 4:10

The error message should probably include details of how to fix it too, with examples if possible.

XML is not really always a user-friendly medium, especially when a strict XSD schema is involved. Is it possible to rethink this requirement, so that an alternative method is used, or perhaps allow the XML and/or XSD to be created via a nice UI?

  • You're really asking: Why the config file? An Excel spreadsheet or data-entry form may be more useful and usable for the intended audience. – JeromeR Jul 24 '15 at 4:10

I think part of making the error message clearer for non-specialists is to indicate what the user can do to fix it. Is there something they can check on? Someone they should contact? Documentation they can consult?

  • Yes: better than "It fails" is some idea of what to do next. – JeromeR Jul 24 '15 at 4:11

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.