

EcoDyn writing wiki - tips for good writing and proper formatting.
General
-
Try your best to judge what you write from the point of view of someone that has never seen your work before. Things that might be obvious to you and to your co-authors won’t be for an outside reader.
-
There is some debate about it, but in current ecology writing the preference seems to be use of active voice, in plural first person (We did, we applied, etc.). This is the preferred style for EcoDyn.
-
When mentioning numbers in your text, zero to ten are spelled out as words, numerals are only used from 11 and beyond. It makes reading easier.
-
Acronyms (siglas) must be always spelled out on their first appearance in the text, no matter how obvious you think they are. If you want to translate it, then give the full translated name, then the full original name, then the acronym.
-
Bad: "We calculated NDVI". Good:"We calculated the Normalized Difference Vegetation Index (NDVI)".
-
Bad: "Nós calculamos o Índice de Vegetação da Diferença Normalizada (NDVI). Good: "Nós calculamos o Índice de Vegetação da Diferença Normalizada (Normalized Difference Vegetation Index, NDVI)".
-
-
Abstracts and figure/table captions are supposed to be independent of the main text, so spell out the acronyms when used in these contexts.
-
Be consistent with your terminology. If something was first called a "class", don't refer to it later as a "group"or a "cluster". If you named your variables, use always the same exact names to refer to them.
-
Be consistent with your units too. Give preference to S.I. units, decide which unit and order of magnitude is best for reporting your numbers, and stick with it.
-
Do not start sentences with numbers. 100% of the time, it reads horrible.
-
When reporting dates and times, use the ISO 8601 standard (yyyy-mm-dd hh:mm:ss.sss ±tz), and don't mix and match notations throughout the text.
-
Also, remember that only mathematical and statistical models have variables. When talking outside or models, don't use the term variable. Use "phenomena", "characteristic", "process", "trait", "factor", etc. These are the actual things you are studying, which only become "variables" when represented mathematically by some sort of measurement. To help the reader, write the "thing" without caps (e.g. fire, precipitation), and the variables with capitals and/or quotes ("Fire", "Precipitation").
-
Don't abuse acronyms, they make for extremely hard reading for people unfamiliar with your work, especially when not representing mathematical variables. Yes, it's tiring to write the full variable names every time. So use the acronyms while writing, then do a Search & Replace when you're done, and voilá.
-
By the way, terms in languages different from the main language of the text should be italicized, capisci?
-
Always acknowledge your funding! Even if it is a partnership that is not part of your main project, the only reason you have the time and freedom to work on it is because someone else is paying your salary. So acknowledge it!
Title, Abstract and Keywords
-
Title and abstract are the most important parts of your paper, as they determine whether someone will actually read your paper or not. As they must capture the essence of the work, they should always be written last.
-
Titles should strike a balance between too general (uninteresting) and too specific (almost a second abstract). Don't include study area names unless the actual location is of particular importance or relevant to the questions (and not just a system for testing ideas). As a rule of thumb, titles should never exceed two lines of text.
-
The abstract must give a full overview of the most important parts of the paper, which are often the main findings. A lot of people write abstracts by summarizing the main text in order,which means they usually run out of space at the methodology, and include no results at all. If you don't know your work well enough to write a short summary of it from scratch, clearly poitning out the main outcomes of the work, then you are not ready to write about yet.
-
At least the title and the keywords will always be indexed on bibliographic databases, so don't repeat words from the title on your keywords. Use them to complement the title.
Introduction
-
The purposes of the introduction section are to establish what is the state of the art of your field of study, what are the knowledge gaps, and why filling these gaps is necessary. Remember the baby - werewolf - silver bullet metaphor.
-
At the last paragraph of your intro, you should clearly state your questions or hypotheses (not objectives!) . Everything else in the paper is conditioned to answering/testing these questions/hypotheses. Enumerate them!
-
Do not summarize the next sections of your paper at the end of the intro, it is short enough for people to get what is in it. Don't summarize the relevance of the paper either, that is the job of the conclusion.
-
Do not say a bunch of things in a paragraph, then add a single reference at the end. It will not be clear to the reader that everything you wrote came from the same source, because...
-
...if all lines on an intro paragraph come from the same source, it means that you are not reading enough about your subject. In other words, you’re not writing, you’re transcribing from a single source, and that in the best case scenario is being lazy, and in the worst case plagiarism.
-
Let me say that again: plagiarism. You cannot transcribe sentences from other sources, unless:
-
It is something so simple there isn’t another way to write it (but probably there is)
-
You are using a direct quote, with the transcription within quote marks: "...". Social sciences like them a lot, natural sciences not as much.
-
Regardless of scientific field, don't abuse direct quotes. They only make sense when not only the content, but the actual wording of the passage is important to give context to the reader.
-
You (and I) can get in serious trouble for plagiarism. Maybe it seemed ok to do it for a class assignment (it was not), but it is unacceptable under any circumstance.
-
-
Citations must support your statements directly. When you cite a paper to support your claim, it is because the results of that paper support it, and not because, somewhere in their introduction, the authors stated the same thing as you. In fact, I bet the authors already cite someone else when making that statement, so go to the source. In very, very rare cases you may use "apud" because you can't find the original source, but on this day and age, most sources are available, if you make the effort to look for them.
-
Be clear and precise in your statements. Avoid platitudes or "motherhood statements", the sort of "feel-good"statement that cannot be proved right or wrong, and therefore carries zero in formation:
-
Bad: "The Amazon is one of the most important ecosystems in the world (REF)".
-
Good: "The Amazon is an important ecosystem, as it has one of the largest species richness in the world (REF) and participates actively in regional and global climate regulation (REF)".
-
Better: "The Amazon is an important ecosystem, as it has one of the largest species richness in the world, with more than X thousand species of plants and Y thousand species of animals (REF), Y% of them endemic (REF). The Amazon system also participates actively in regional and global climate regulation, by adding X tons/year of water to the atmosphere and by affecting the behaviour of the atmospheric currents by altering radiative and convective processes (REF)".
-
Methods
-
The baseline for judging the methods section is reproducibility. Your methods must be detailed enough to allow anyone that is reading it to be able to reproduce everything you did.
-
However, the methods section is not a user guide or a manual. The readers must be able to reproduce the method, not necessarily operate the software / process the lab samples the exact same way you did.
-
Bad: the samples were taken to the lab in Ziploc (tm) plastic bags, then transferred to 200ml paper bags before being placed horizontally on the oven for drying using the 60 degrees setting of the XPTO-2000 drying oven.
-
Good: Samples were over dried for 48 hours at 65 degrees and weighed to the nearest 0.1g.
-
Very often, the best order to present what you did may not be the order in which you did it. Don’t write your methods like a narrative of your past months. Try to to see it from the point of view of someone unfamiliar with your work.
-
It usually more intelligible if you first list the data you used, and how it was acquired, and then start describing the analyses done with this data. It is very confusing when new data "pops-up" in the middle of the analysis.
-
For remote sensing data, you always need to specify: satellite, sensor, date of image acquisition, scene identifiers (e.g. Landsat path/row), acquisition mode (if relevant), processing level / product name, and source of the data. For processing and products, cite the relevant papers or technical documents.
Results
-
Which results should you include? Whichever are necessary to answer your questions / support your hypotheses. It is common, especially for papers coming out of theses, to try and cram in everything you did.
-
Science means experimentation, which means some of the things you did helped, others didn't. Focus on what is necessary to tell the story / answer the questions.
-
You will often "wander off"on different things and different ideas while doing your research. This is great, and expected, but again, not everything you did should be put on a single paper. Focus on the main questions and the main message. There are always more papers to write.
-
-
Present your results in the same order that you presented the questions and the methods, to give a sense of continuity.
-
Make good use of figures and tables to show the "comprehensive results", and use the text to help the reader focus and make sense of the most relevant parts. There's nothing more boring than several paragraphs just enumerating value after value.
-
Bad: "Group 1 had a mean of 5.2, while Group 2 had a mean of 3.7, Group 3 a mean of 1.3 and Group 4 a mean of 2.2. Standard deviation for Group 1 was 6.2, with a value of 4.7 for Group 2, 8.9 for Group 3 and 7.2 for Group 4".
-
Good: "Averages ranged by a factor of 4, from 1.3 (Group 3) to 5.2 (Group 1). Group 1, however, was the most variable (sd = 6.2), by a factor of ~2 (Table 1)".
-
-
Discussion and Conclusions
-
A good discussion is the hardest part of the paper to write. It is where you analyze the implications, strengths and/or limitations of your results, in light of what is already known in your field of study. It is also where you effectively answer your proposed scientific questions. That means you really need to know your field. If you are struggling to write your discussion, put the manuscript down and go read more about your subject.
-
Comparisons against the existing literature should be meaningful. Remember, you are analyzing your results against the state of the art of your field, not against specific publications. Don't write your discussion as a checklist of comparisons against a ad-hoc predefined set of papers.
-
I prefer "Conclusions" to "Conclusion" as the real objective is not just to finish your text (Conclusion), but to put your main findings in the broader context of your scientific field (Conclusions). How is science better after you paper? This should be in close connection with your intro; there, you establish the state of the art and the major gaps; here you show how your study pushed this state of the art by closing some of these gaps (and/or identifying previously unknown gaps).
-
The Conclusions section is not a second abstract. The abstract summarizes the whole paper, from intro to the conclusions themselves. This section is about distilling the essence of your scientific contribution and framing it agains the broader context of your field of research.
Figures and Tables
-
The quality of the figures shows how much you care (or not) about your paper/work. Reviewers will tend to care just as much when they see them. So make good looking, captivating and legible figures.
-
Before making a figure, think about at which size it will be printed/viewed. Then make sure your lines and fonts are easily readable at this size. Rule of thumb: it's bigger that you think.
-
Figure and table captions must be comprehensive, so as to make sense without needing to read the main text.
-
Bad: "Location of the study area".
-
Good: "Location of the Parque Nacional Serra do Cipó and Área de Protecão Morro da Pedreira (Minas Gerais, Brazil) where fire occurrences were mapped using a time series of Landsat images from 1984 to 2015."
-
Proper table formatting for reading: no outside borders, no vertical lines. Use only horizontal lines, and only to separate major components.
-
All figures and tables must be cited in the relevant parts of the text, there can no "disconnected" figures or tables. If you're not sure where the figure/table should be cited, either you are forgetting to write about something, or the figure/table is not relevant.
-
Do not use a full sentence to just refer to a figure or table. It uses up space and carries no information. Say something relevant about the results presented in the table/figure, and then cite it using parentheses.
-
Bad: "The results are show on Figure 1. Group 1 was higher than Group 2".
-
Bad: "Group 1 was higher than Group 2, as can be seen on Figure 1".
-
Good: "Group 1 was higher than Group 2 (Figure 1)".
-
Use first capital letters unless explicitly told not to. Good: (Figure 1). Bad: (figure 1).
-
-
Except when explicitly told otherwise, table captions go on top of the table, and figure captions go under the figure.
-
Use the same font for all figures, to maintain consistency.
-
For maps with a continuous colour scale, the legend cannot be discrete (squares). ArcGIS does continuous (gradient) legends, QGIS doesn't. But...
-
To improve your maps, use GIS software to set the scale-dependent layout (scale bar, grid) and colours, and then draw/write on top of it using Inkscape. It will be much easier to add custom elements to your final map.
Equations
-
Unless they are very simple, equations should be given separately from paragraphs, and properly cited and numbered (just as figures and tables).
-
Bad: "We calculated NDVI as (NIR - RED)/(NIR + RED), where NIR".
-
OK: "We used a model of the type y = a + b, where y is ...".
-
Good: "We calculated the Normalized Difference Vegetation Index (Equation 1):
-
(Equation 1)
-
R notation is not mathematical notation. Your regression model is Y = a + bX, not varname1 ~ varname2.
Formatting
-
If your document will be printed in Brazil or the UK, make sure you are using A4 page sizes. If it will be printed in the US, use letter size. Check before you start formatting your text.
-
In fact, set page size and margins before you format anything else.
-
Headings and subheadings should be aligned with the left margin, with no paragraph indentation. Word is stupid and will indent them, fix that. Or better yet, don't use Word.
-
Learn to set and use text styles for headings, subheadings, and captions, they will make your life very easy.
-
Also learn to use Figure and Table references to avoid skipping numbers, and make your life easier if things change positions.
-
If you use styles and references properly, making indexes is a breeze.
-
Be consistent with your paragraph formatting (first line indent, line spacing, spacing between paragraphs
-
Don't use blank lines for spacing, learn to format your paragraphs and titles.
-
Option: learn to use Rmarkdown or LaTeX, and never worry about this crap again. A very good way to start using LaTeX with minimal hassle is to use Overleaf. If you share a manuscript with me written on Overleaf, I will love you forever.
-
If there is no way around breaking a table into two or more pages, repeat the caption at the top of each part, using Table 1 (cont.).
Dicas específicas para Português
-
Cuidado com as frases sem sujeito! Ex.: "A área de estudo está localizada na região leste. Possui um relevo acidentado...". Quem possui um relevo acidentado?
English-specific tips
-
"In order to" is mostly unnecessary. It doesn't add to or change anything in the sentence. And remember that it is better to use active voice.
-
Bad: "In order to calculate average responses..."
-
OK: "To calculate average responses...".
-
Better: "We calculated average responses..."
-
-
Be confident about your work. On your proposals, and most definitely on your papers, you will never "aim to", "attempt to", "try to", etc. You will do (proposal), or did (paper). Remember Master Yoda: DO, OR DO NOT, THERE IS NO TRY.
-
-
Avoid excessive "flourishing", especially if youare a native Portuguese speaker. For clear and simple science writing , you mostly only need "are/were", "do/did", "show/showed". The data or results don't need to "present", "exhibit", or"highlight". They may, in specific contexts, "suggest". And avoid using expressions like "the data demonstrate", or "the results emphasize". The results are not people, the authors are, so "we demonstrated", "we emphasized", and so on.
For non-native English speakers:
-
One species, ten species (specie is not a word).
-
One hundred, two hundred. "Hundred"does not make sense if used alone.
-
Don't use "the" except when referring to a specific, unique thing. Ten individuals, the first individual.
