One of the main problems reading an immature technical text is that it does not make consistent use of a clear terminology (also, wrongly, called vocabulary or glossary). A clear terminology emerges as you do your research, and you need to be in control of it. Even the simplest and most obvious concepts need to be referred to in a consistent way (e.g. “user” or “end user” or “customer”, which one to use?). Here are some suggestions:
- Explicitly define and continuously refine your terminology: Work continuously with your terminology and give meaningful names to things you define. If you see yourself repeating the same phrase (e.g. “All the users below the age of 30”) many times in your text, this phrase might be a candidate for being replaced with a term/name. Do your terminology work systematically. Use a table or, even better, UML class notation to be as formal as you can. Being formal in technical writing is not a bad thing!
- Get to know the jargon of your field: Once you have defined your research topic, try consciously to learn and use the jargon commonly used in your field. Don’t forget to include the definition of the jargon terms you use in your terminology table! Also, don’t overuse jargon. It can make your text difficult to read for non-experts.
- Define your terms the first time you use them: In your report/paper don’t forget to provide a short definition of your terms the first time you use them. Don’t use a term without also showing what you mean by that term. Index your first definition of a term in your index chapter at the end of the document so it is easy to look up definitions (or have all your definitions in a table).
- Use your terminology! Don’t just define the terms, use them consistently in your report. Using the defined terms consistently not only allows the reader to quickly become familiar with them, but it also makes your text more consistent and more concise.
- Don’t overdo! The only terms that need to be defined by you are the ones directly related to your problem domain. This is tricky as it takes time to develop your understanding of your problem domain, and to focus your writing. There exist accepted definitions of many terms out there (e.g. in Wikipedia). Use these definitions as much as possible for terms that are not central for your problem area.