Best Practices for Journal Documentation
General Guidance:
The Journal entry applies to the given Worksheet (there is one Journal per Worksheet); Journal should be used to document the objective, analysis steps (in replicable detail), and outcome of the analytical step performed in the current Worksheet. We suggest presenting your overall analysis (outcomes, objectives, key figures, and a summary of the analysis steps, with links to the relevant Worksheets/Journals) in an Organizer Topic.
Lead with major conclusions/objective, then summarize detailed analytical steps.
Be concise: Minimize jargon, remove unnecessary “filler” words, focus on saying exactly what is meant.
What does a Great Journal Entry Include?
Title
The title should concisely describe the objective and/or conclusions of the individual Worksheet (we recommend summarizing the overall Analysis objectives/conclusions in an Organizer Topic and inserting links to these Worksheets; overall Analysis objectives may also be useful in the first Worksheet)
Objective
An Analysis should explore a unified problem or theme in which each individual part of the analysis (e.g., data cleansing or finding periods of interest) is done in a Worksheet. It is often helpful to articulate the objective of the workstep, as precisely as possible, in the Worksheet.
e.g., " Objectives: 1) Evaluate changes in column efficiency over time using HETP (higher HETP values = fewer resolved separations per unit length of column and decreased column efficiency). 2) Determine maintenance schedule based on HETP performance (i.e., schedule maintenance just before HETP exceeds the maximum acceptable threshold)."
Analytical Approach
It may be helpful to outline and defend the generalized analytical approach in Journal, especially if there are multiple possible approaches and/or this approach differs from common methods. Detail any relevant equations and include citations (e.g., [1]; place references at the end of the Journal entry for readability).
e.g., "Use the normalized Direct Transition Analysis method [Smith et al., 2018]"
Detailed Analysis Steps
Describe analyses and calculations concisely, in replicable detail: name tools and criteria used, paste text of any Formula calculations (use your judgement for large pieces of code), and insert Seeq links to Worksteps, time ranges, and data liberally.
e.g., “Use [tool] to [explain outcome]. (Workstep Link)”
Name variables appropriately when showing Formula in Journal (e.g., “$volume” instead of the default “$a”, “$b”…).
In Journal, describe large pieces of code in words instead of pasting in the Formula itself.
Add comments inside large pieces of Formula code to explain the steps taken in the calculation.
These practices facilitate collaboration and allow people with “View Only” access to follow the analytical process, as they cannot click “Edit” to see the tools/Formula(s) behind a signal, condition, etc.
Insert images and exterior links to help document your analytical procedure.