Clarity

Stylistic choices, and the choice of expressions and formulations must be made with the purpose of facilitating the reader's understanding of the text, not in order to embellish or otherwise complicate the presentation.
Terminology, variable names, abbreviations and acronyms must be explained properly. Any definitions must be specific and concrete, and written using terms and concepts that are already known to the reader, clear, and otherwise well-defined. Illustrating examples may be used to clarify or exemplify a definition; they may not replace a definition entirely. Synonyms should not be used unless necessary.

Examples
"After reviewing our code, we realized that the initial test values would not work. After some changes, however, we obtained the results in Figure 3."
The mentioned changes have not been detailed, nor have the coding errors been explained sufficiently. (Why would the initial values not work?)

"After reviewing our code, we realized that the initial test values would not work, since the variable test_1 was being assigned the wrong value due to an error in the X module. After correcting this error, we obtained the results in Figure 3."
The authors are now describing the error in more detail. Some information is still lacking, however: an explanation of what is stored in the test_1 variable, and how this affects the result. The authors also need to state what they did to modify the code in the X module (perhaps by showing a code sample and discussing that).

"We use a JSON object to store ..."
No explanation of JSON.

"We store information about each actor as a JSON object. JSON can be used, e.g., to store information about people, so it is a good choice in our project."
The authors are explaining what JSON can be used for, but not defining what it is.

"JSON is a text-based format for storing data (e.g., information about a person). We store information about each actor as a JSON object."
The authors are first explaining what JSON is, then they present an example of what it can be used for, and finally they explain that they are using this format in their work for a particular, mentioned, purpose.

"We are using test data provided by [Company X's] system, as well as from our own prototypical system. We are, however, using the same tool as [Company X]. This lets us generalize our results and compare them.
It is not clear what 'This' refers to here, i.e., what makes it possible to generalize? The fact that two sources of test data have been used? Or that the same tool has been used to obtain both sources?

"The term X denotes a new phenomenon that deals with the analysis of test data. The name itself is not very informative, but as the expression indicates, ..."
The words 'term', 'name', and 'expression' are used to refer to the same thing (X), which makes it difficult to comprehend what the authors are trying to say.

"The term X refers to a number of different methods for analyzing test data. Often, however, the term X is used to denote..."
This version is more clear, and the word 'term' consistently used to describe X.

Back to Academic text