Organization, Documentation, & AI Assistance
Your project is in its early stages right now but the best way to get organized is to set things up so that you stay organized. So, before you organically accrue many project files, we’ll discuss some useful tenets of project organization and documentation (two tightly-related concepts) and how they apply to synthesis work. We’ll also discuss responsible use of generative artificial intelligence (genAI), and hopefully prompt some reflection about whether, where and how you might use these tools in your research.
Reproducibility Best Practices Summary
Making sure that your project is reproducible requires a handful of steps before you begin, some actions during the life of the project, and then a few finishing touches when the project nears its conclusion. The following diagram may prove helpful as a coarse roadmap for how these steps might be followed in a general project setting.
Project Documentation
Much of the popular conversation around reproducibility centers on reproducibility as it pertains to code. That is definitely an important facet but before we write even a single line it is vital to consider project-wide reproducibility. “Perfect” code in a project that isn’t structured thoughtfully can still result in a project that isn’t reproducible. On the other hand, “bad” code can be made more intelligible when it is placed in a well-documented/organized project!
Documentation
Documenting a project can feel daunting but it is often not as hard as one might imagine and always well worth the effort! One simple practice you can adopt to dramatically improve the reproducibility of your project is to create a “README” file in the top-level of your project’s folder system. This file can be formatted however you’d like but generally READMEs should include:
- Project overview written in plain language
- Basic table of contents for the primary folders in your project folder
- Brief description of the file naming scheme you’ve adopted for this project.
Your project’s README becomes the ‘landing page’ for those navigating your repository and makes it easy for team members to know where documentation should go (in the README!). You may also choose to create a README file for some of the sub-folders of your project. This can be particularly valuable for your “data” folder(s) as it is an easy place to store data source/provenance information that might be overwhelming to include in the project-level README file.
Finally, you should choose a place to keep track of ideas, conversations, and decisions about the project. While you can take notes on these topics on a piece of paper, adopting a digital equivalent is often helpful because you can much more easily search a lengthy document when it is machine readable. We will discuss GitHub elsewhere in the course, but GitHub offers something called “issues” that can be a really effective place to record some of this information.
Project Organization
“Organization” is a big topic but can have serious ramifications for how well/easily you can work on a big, collaborative, synthesis project. To make this more manageable, let’s tackle project organization from the ‘top’ and work our way down to more granular facets of organization.
The simplest way of keeping a reproducible project organized is using folders and file names to effectively keep different categories of content separate. There is no single “best” way of doing this so long as you are consistent. Consistency will make your system–whatever that consists of–understandable to others.
Let’s consider some tenets of good organization that you might consider adopting!
The Project Folder
Use one folder per project! Keeping all inputs, outputs, and documentation in a single folder makes it easier to collaborate and share all project materials. Also, most programming applications (RStudio, VS Code, etc.) work best when all needed files are in the same folder.
Note that how you define “project” may affect the number of folders you need! Some synthesis projects may separate data harmonization into its own project while for others that same effort might not warrant being considered as a separate project. Similarly, you may want to make a separate folder for each manuscript your group plans on writing so that the code for each paper is kept separate.
Smart Sub-Folders
Organize content with sub-folders but keep it reasonable. Putting files that share a purpose, source, or theme into logical sub-folders is a great idea! This makes it easy to figure out where to put new content and reduces the effort of documenting project organization, because the sub-folder names are themselves partial documentation for their purpose!
However, don’t overdo it! Making an intricate maze of sub-folders is just as bad for collaborative settings as having everything loose in the top-level project folder. Just one level of sub-folders is enough for most projects. If you find yourself tempted to use deeply nested sub-folders, consider whether you’ve defined the project correctly–it could be a sign that there are really several separate, albeit related, projects at play.
Quarantine External Content
This can sound harsh, but it is often a good idea to “quarantine” files received from others until they can be carefully vetted and fit into the proper place in your organization schema. This is not at all to suggest that such contributions might be malicious!
Quarantining inputs from others gives you a chance to rename files to be consistent with the rest of your project as well as make sure that the style and content of the code also match (e.g., use or exclusion of particular packages, comment frequency and content, etc.)
Context-Rich Yet Brief Names
Balance information-density with brevity. An ideal folder/file name should give some information about the file’s contents, purpose, and relation to other project files while still being fairly short. These are definitely conflicting perogatives but trying to ‘thread the needle’ will yield better fiile names.
In your search for brevity, avoid confusing acronyms or abbreviations! It can be tempting to make your file names short by adopting bizarre abbreviations but this results in a worse (i.e., less informative) outcome than just having file names that are slightly too long.
Keep in mind too that if your folder names and order are informative, some of the information burden can be lifted from the files by themselves. For example, if you have a folder called “reports”, you could exclude that word from all the report files contained within the folder and instead emphasize report topic or date of creation.
Human-Machine Agreement
File names should be sorted by a computer and human in the same way. Computers sort files/folders alphabetically and numerically. Sorting alphabetically rarely matches the order scripts in a workflow should be run (e.g., “analysis.r” might be the top script in your GitHub repo but is unlikely to be the first step of your workflow).
For scripts, if you add a number to the start of the file indicating its order in the workflow, the computer will sort the files in an order that makes sense for humans reviewing the project. You may also want to “zero pad” numbers so that all numbers have the same number of digits and sort correctly (e.g., “01” and “10” vs. “1” and “10”).
No Special Characters
Avoid spaces and special characters. Spaces and special characters (e.g., é, ü, etc.) cause errors in some computers (particularly Windows operating systems). You can replace spaces with underscores (_) or hyphens (-) to increase machine readability. Avoid using special characters as much as possible. You should also be consistent about casing (i.e., lower vs. uppercase).
Consistent Delimiters
Be consistent with which delimiters you use and when. “Delimiter” are characters used to separate pieces of information in otherwise plain text. Underscores are a commonly-used example of this. If a file/folder name has multiple pieces of information, you can separate these with a delimiter to make them more readable to people and machines. For example, you could name a folder “coral_reef_data” which would be more readable than “coralreefdata”.
You may also want to use multiple delimiters to indicate different things. For instance, you could use underscores to differentiate categories and then use hyphens instead of spaces between words. For example, “data_coral-reef” instead of “data_coral_reef”.
Consider Slugs
Use “slugs” to connect scripts with their outputs. “Slugs” are human-readable, unique pieces of file names that are shared between files and the outputs that they create. Weird or unlikely outputs are then easily traced to the scripts that created them because of their shared slug.
For example, all outputs of a script named “02_tidy.r” should start with “02_”.
Organizing Example
These tips are all worthwhile but they can feel a little abstract without a set of files firmly in mind. Let’s consider an example synthesis project where we incrementally change the project structure to follow increasing more of the guidelines we suggest above.
Top-level sub-folders are colored blue so that the high-level structure is easier to quickly scan.
synthesis-project
|– clean-data.csv
|– community data.csv
|– graphing.r
|– ordination-plot.tiff
|– results report V2.pdf
|– results report V2.qmd
|– results_DRAFT.qmd
|– scatterplot.jpg
|– spp-boxplot.png
|– stats-feb 2024.r
|– synthesis-project.Rproj
└ - Wrangle.r
Positives
- All project files are in one folder
Areas for Improvement
- No use of sub-folders to divide logically-linked content
- File names lack key context (e.g., workflow order, inputs vs. outputs, etc.)
- Inconsistent use of delimiters/casing
synthesis-project
|– data
| |– clean-data.csv
| └ - community data.csv
|– graphs
| |– ordination-plot.tiff
| |– scatterplot.jpg
| └ - spp-boxplot.png
|– reports
| |– results report V2.pdf
| |– results report V2.qmd
| └ - results_DRAFT.qmd
|– scripts
| |– graphing.r
| |– stats-feb 2024.r
| └ - Wrangle.r
|– LICENSE
|– README.md
└ - synthesis-project.Rproj
Positives
- Sub-folders used to divide content
- Project documentation included in top level (README and license files)
Areas for Improvement
- File names still inconsistent
- File names contain different information in different order
- Mixed use of delimiters
- Mixed use of upper/lowercase
- Many file names include spaces
- Code file order not clear from filenames
synthesis-project
|– data
| |– raw-community-comp.csv
| └ - tidy-community-comp.csv
|– graphs
| |– abundance boxplot.png
| |– abundance scatter.jpg
| └ - comm ordination.tiff
|– reports
| |– results feb 14 2024.pdf
| |– results feb 14 2024.qmd
| └ - results may xx 2024.qmd
|– scripts
| |– data analysis.r
| |– data tidying.r
| └ - graphing.r
|– LICENSE
|– README.md
└ - synthesis-project.Rproj
Positives
- Most file names contain context
- Standardized use of casing and–within sub-folder–consistent delimiters used
Areas for Improvement
- Workflow order “guessable” but not explicit
- Unclear which files are inputs / outputs (and of which scripts)
synthesis-project
|– data
| |– 00_raw-community.csv
| └ - 01_tidy-community.csv
|– graphs
| |– 02_abundance boxplot.png
| |– 02_abundance scatter.jpg
| └ - 02_comm ordination.tiff
|– reports
| |– results_2024-02-14.pdf
| |– results_2024-02-14.qmd
| └ - results_2024-05-xx.qmd
|– scripts
| |– 01_tidy.r
| |– 02_graph.r
| └ - 03_analyze.r
|– LICENSE
|– README.md
└ - synthesis-project.Rproj
Positives
- Scripts include zero-padded numbers indicating order of operations
- Outputs share zero padded slug with source script
- Report file names machine sorted from least to most recent (top to bottom)
Areas for Improvement
- Could add subfolder-specific README files
- Depends on complexity of respective subfolder
- Graph file names still include spaces
Responsibly Using Generative AI
Generative AI (hereafter “genAI”) is a rapidly evolving topic. The pace of new tool development outpaces our ability to track the myriad of potential applications for ecological synthesis. At the same time, there are real costs to using AI, so we encourage intentional decision-making around its use. The goal of this lesson is to give you a starting point for thinking about genAI and deciding whether/how you would like to use these tools. We will not provide comprehensive coverage for how AI works, or provide tutorials on specific AI platforms today. We are by no means experts in the design and application of AI, we are just curious and excited (and sometimes apprehensive) about the possibilities these new tools offer.
Big Picture
GenAI results are probabilistic rather than deterministic. The same exact prompt is not guaranteed to return the same result. This means that genAI results are not reproducible (i.e., cannot be guaranteed to return the same output from the same inputs) so should be used with caution when reproducibility is a priority. However, you might ask a genAI tool to help you generate code to analyse your data that you can review, modify, save and rerun.
Whether and how to use genAI for these projects is something your team will need to decide on collaboratively. The potential applications and drawbacks described below–or that you’ve encountered in your own work–may provide helpful context for that conversation. But the key point is that aligning expectations and developing group norms around AI are a key part of a successful scientific collaboration.
Finally, note that you have a professional obligation to verify and validate genAI output. This requires some fundamental understanding of the task so that you can provide adequate human oversight. Remember that the same truism that applies to non-AI coding also applies here: the worst case isn’t that your code gets an error, it’s that your code appears to work but does not actually do what you intend!
AI Use-Cases
There are a handful of particularly well-recognized potential use-cases for genAI in a typical researcher’s toolkit. A non-exhaustive set of these is included below.
Many video conference platforms (e.g., Microsoft Teams, Zoom) now include AI components that take meeting notes and may even provide executive summaries of key points and/or action items.
Most general purpose chatbots can do basic research when prompted. But, all AI tools reflect the biases in their training sets and have a strong tendency for sycophancy as a result of model training that rewards agreeableness. As a result, AI adoption narrows the diversity of research topics pursued (Hao et al. 2026) and AI chatbots tend to support rather than challenge user’s views (Naddaf 2025). While general purpose AI tools often ‘hallucinate’ scientific publications, those which retrieve information from curated databases of scientific papers may help researchers discover new papers more effectively than traditional search. Specialized genAI tools are being developed for literature search and scientific brainstorming(Gottweis et al. 2026) that reduce the tendency to fabricate references. If you are interested in experimenting with tools such as Consensus, SciSpace, Elicit (all commercial applications), or Asta (a non-profit alternative), evaluate the outputs with the potential impact on research creativity in mind. In sum, use genAI to supplement, rather than replace, the bright minds around you.
While most people would consider using AI to write a scientific paper in its entirety unethical, there is often a fuzzy line between using AI to help with editing versus writing. For example, you might use AI as a thesaurus, to provide suggestions on how to improve clarity of a sentence or paragraph, to correct grammar or help with syntax when writing in a second language. In July 2026, ~190 organizations signed onto the Code of Practice on Transparency of AI-generated Content, and AI companies have begun watermarking AI-generated text in an effort to reduce the use of undisclosed AI across many domains, including scientific writing (Gibney 2026).
From writing original code, debugging or reviewing code, refactoring code you’ve already written to run more efficiently or translating between coding languages, AI coding assistants can be incredibly valuable for speeding up the process. At the same time, vetting the output of AI-generated code is essential, and doing so effectively requires the subject matter expertise to define appropriate goals, understand the code and set up effective testing strategies. Researchers should treat AI-generated recommendations as suggestions rather than decisions, and verify that the chosen approach reflects the research question, sampling design, data characteristics, assumptions, and relevant disciplinary knowledge.
The sycophantic tendencies also provide challenges for integrating AI into data science tasks, where LLMs have been documented to ‘see’ what they expect to see (Couch and Altman 2025). The confident ‘tone’ of AI responses can mask underlying uncertainties. A recent evaluation in fisheries modeling concluded the AI agents reliably write functional, but not necessarily scientifically accurate code (Brown et al. 2026).
If you’re new to coding, or to a particular programming language or type of statistical analysis, we encourage you to invest some time in the desirable difficulties of learning (see Learning and Critical Thinking, below). This likely involves working through some basic material without relying on AI to simply write the code for you, and experiencing some frustrating code failure along the way. You may also consider using AI as a learning tool to explaining code written by others or to explore statistical approaches, explain unfamiliar methods, identify assumptions, and suggest diagnostic tests.
Flavors of AI Coding Tools
There are a few different ways with which you can engage genAI tools. The costs and benefits in terms of speed and human control tend to be inversely related, with the degree of human-in-the-loop interaction decreasing as you move to increasingly agentic tools, which work more independently, and faster.
Perhaps the easiest entry to genAI coding tools is to use your web browser to navigate to a chatbot of your choosing and prompt it for help generating or editing code. After vetting the code it produces, you can then copy and paste it onto your local machine to run. Prompts can take the form of “pseudocode”, where you describe what you wish to achieve using natural language, or you can copy actual code, console outputs, or upload (small) files to get increasingly specific help.
You can use genAI as an assistant that is directly tied into your IDE (Integrated Development Environment, such as R Studio, Positron, or VS Code) that essentially looks over your shoulder and suggests code as you are writing it or provides a chat window right in your IDE that can answer questions, edit and write code. The advantage of the “pair programming” model is that the LLM understands the context of your project, which can help you iterate more efficiently. A variety of tools are available for this. Some example include Positron’s ‘Posit Assistant’, or any number of plugins for IDEs such as Visual Studio Code. Some plugins are tied to a particular model provider (e.g.commercial ones such as GitHub Copilot, Claude Code, Codex), others such as Zoo (formerly Roo) and Cline code allow you to bring your own key, decoupling the harness (the software that allows you to interact with a particular LLM) from the model provider itself.
In agentic mode, AI moves beyond providing suggestions to carrying out multi-step tasks on a researcher’s behalf. For example, an agent can explore project files, write and modify scripts, run code, inspect errors and outputs, create tests, update documentation, and revise its approach based on results. With appropriate connections, it can also interact with tools such as GitHub, databases, and web services. Mistakes may be harder to catch because of the volume of generated code to review, but the rate of code development is typically faster. When using AI for scientific research, the human-in-the-loop supervision requires careful planning before implementation as well as breaking the agent’s workflow and outputs into manageable chunks that can be reviewed and tested. Adherence to the security recommendations below is also paramount.
AI Drawbacks
This section highlights select drawbacks of generative AI, which may provoke your thinking on whether and how to use AI for a particular task.
There is an inherent tension between the ease with which a task can be accomplished and its value to learning. The concept of desirable difficulties describes learning activities that require more effort and take more time, but lead to deeper learning and better retention (Bjork 1994). Using generative AI allows you to complete a task quickly but come with a cost to development of critical thinking skills, memory, and neural connections in your brain (Kosmyna 2025).
How you use AI can also influence your learning outcomes. For example, a (small) Anthropic sponsored study of software engineers observed that skill-development was higher among programmers who use AI not simply to produce code, but also to ask questions and request explanations (Shen and Tamkin 2026).
Research also suggests that while AI tools may increase productivity for individual scientists, it may narrow the diversity of scientific inquiry (Hao et al. 2026).
In this course, we challenge you to think about what skills you want to develop and invest the time and effort to do those tasks without the assistance of genAI. Other tasks you may be happy offloading on an AI assistant, but do so with awareness of the impacts on your own learning and creative output.
Agents running on your machine generally inherit the permissions of the user who is logged in. This allows them to do anything you can do, including reading, modifying and deleting files, accessing the web, installing software, and executing code. Access to your private data, exposure to untrusted content and ability to externally communicate (aka the “lethal trifecta”) make agentic coding particularly dangerous. Agents may install malicious code or follow nefarious instructions hidden on a website, such as instructions to reveal confidential information. The safest option for using agents is working in a sandbox completely isolated from your computer, such as a virtual machine. Next best is to review and approve any AI-generated suggestions, including always reviewing code written by genAI before executing it.
The cumulative environmental footprint of genAI is concerning (Programme 2024). Breaking down the problem reveals that the environmental impacts depend not just on whether you use AI, but where, and how.
AI Queries – Because of the pace of development in AI tools, it is impossible to give exact environmental consequences at the query or token level for today. However, we can cite costs in the (recent) past and be specific about the model where those numbers were calculated. In 2025, a ChatGPT query used about 5 times the energy of an equivalent web search (Zewe 2025). In 2026, a long-input AI query (7500 words) used a similar amount of energy to what is used by a laptop over 5 minutes (Ritchie 2026b). For water use, recent estimates suggest a GPT-4 prompt use about 15 milliliters of water (Szczerba 2026), and a medium-length ChatGPT-5 response used about as much water as running a shower for a quarter of a second (Lo 2025).
AI Agents – Agentic AI tasks consume orders of magnitude more than a short chat. Heavy agentic AI use is where the electricity consumption becomes more environmentally significant. Rough estimates here indicate each person-day of agentic AI use has the energy footprint of running a couple of refridgerators, all day long (Hausfather 2026), or about 7% of the average American’s daily electricity use (Ritchie 2026a).
Data Centers – Data centers are power- and water-hungry, as well as noisy. In 2025, AI-focused data centers consumed 0.5% of the world’s electricity, a number which is projected to grow to 3% by 2030 (Ritchie 2026b). Large data centers may use 1-5 million gallons of water a day, comparable to the daily water usage of a town of 10-50,000 people (Osaka 2023). The large amounts energy consumed by AI-focused data centers exceeds the global totals from “bottom-up” accounting methods based on individual AI queries and agentic AI use. This accounting gap suggests that image and video generation, together with diffuse AI use across the internet and commercial applications are a substantial piece of the global AI environmental footprint (Ritchie 2026a). Furthermore, the environmental impacts in terms of pollution, energy and water costs, and public health are unevenly distributed across the country, with disparate impacts often accumulating in underserved communities (Bharath 2026).
GenAI tools are/were trained on all publicly-available information (in many cases, regardless of license or copyright status) and on users’ ongoing interactions with these tools. Keep in mind that the the original content used to train the models was used without consent, attribution, or compensation for the creators (Appel et al. 2023) and include that in your decision-making process for whether/how to use these tools.
If you use these tools, be sure to check the privacy settings to ensure that you are comfortable with how your interactions are used to train the model you’re using. Most commercial genAI tools default to a setting where they collect your inputs to improve the model, but many of them allow you to opt out. Privacy settings also change over time, so pay attention to communications from your AI model provider. Running a model locally (e.g. on your laptop), or on computing resources provided by your institution can also ameliorate some privacy concerns. Research projects that rely on sensitive data (e.g., Human Subjects research, Indigenous data) require additional guardrails and as a rule should not be used in any commercial AI application.
Access to generative AI tools differs among institutions, regions and with economic resources. Learning and training opportunities are also highly variable (Freed 2026). We will work with students in this course to ensure equitable access for the duration of the class. Use them to understand what is possible, but remember that depending on your professional trajectory, the whims of your institution’s higher-ups and/or the tech vendors providing commercial AI tools – you may or may not have access to similar tools in the future.
AI Disclosure and Tracking
However you choose to use AI, it’s expected that AI contributions to scientific research be disclosed at the time of publication. A few frameworks for categorizing and reporting AI use in scientific publications have emerged (Ahmetoglu et al. 2026; Suchikova et al. 2026), but whatever disclosure statement you eventually write will require remembering what you actually did. This can be challenging when a project has evolved over months to years, due to difficulty in recalling content source (aka “the AI Memory Gap” (Zindulka et al. 2025)). For agentic coding exercises, you might consider setting up a self-documenting workflow, such as instructing your agent to regularly update a prompt action log (example here). When interacting with a chatbot, take a moment at the end of your session to ask the chatbot to summarize the task, platform, and date. We have provided one possible template (see specifically the AI tabs for this exercise).
Learn More
The field of genAI is moving rapidly. While we have attempted to compile contemporary resources at the time of writing (Autumn 2026), they are likely to evolve over the course of the semester and beyond. As well, many citations rely on blog posts and preprints, which may not be persistent.
If you’re looking for current information, ESIIL’s AI-in-a-Day working group is loosely curating a Zotero library of AI-related articles of relevance to environmental scientists. Use the colored tags to filter (see example on the right) and sort by date to find something recent that suits your interests.