Tone
- Write in third person. Avoid addressing the reader directly ("you") or the writer's voice ("we") -- describe what the software does, not what the user should do with it.
- When a sentence needs an actor, name the actual role instead of a generic "the user" catch-all where a more specific one applies (e.g. "the designer" for Designer-role LabIMotion docs).
- Step-by-step instructions stay imperative ("Click Save", not "The user clicks Save") -- the tone rule applies to descriptive/explanatory prose, not to how-to steps.
Spelling
- Use American English throughout (center, gray, color, organize, label, normalize, recognize, behavior, analyze, synchronization -- not the British centre/grey/colour/organise/labelled/normalise/recognise/behaviour/analyse/synchronisation).
- "Set up" (verb, two words) vs. "setup" (noun, one word): "set up a reverse proxy", but "the setup is complete".
- Preserve fixed acronym/product casing exactly: SMILES, InChI, GitHub, Docker, SMARTS, ChemCLI -- never re-case these when copyediting surrounding prose.
Images
- If you're adding an image to illustrate a paragraph, place the image after the corresponding paragraph.
UI references
- Keep inline representations of real UI controls --
<Btn>(from@site/src/js/btn.js) and bare FontAwesome icons -- next to the instructions that reference them, so readers can visually match prose to the interface. - When the UI changes, replace the cue with the new control's representation instead of deleting it (e.g. the v2 add/arrow button became the v3 green "+ CREATE" button, rendered as
<Btn mixed={[faPlus, "CREATE"]} color={"success"}/>). Only drop a cue once the control it represents no longer exists.
Videos
- Embed YouTube references with the
YouTubeFramecomponent (@site/src/js/layout) using ayoutube-nocookie.comURL, rather than a bare link -- consistent with every other video reference on the site. - Plain links remain fine for genuine reference-list entries (e.g. a "further reading" bullet, a channel link) that aren't meant to be watched inline.
Version markers
- Don't add "available from version X onwards"-style notes to individual pages or sections -- the version dropdown already conveys which release a page belongs to, so a blanket marker is redundant with it.
- Do keep narrower sub-version caveats (e.g. "Not available in v3.12") -- those convey real information the version selector itself doesn't capture.
Cross-links
- Link the first meaningful mention of a related concept on a page to its canonical page (e.g. the first "samples" on a page →
/docs/eln/ui/elements/samples). Don't re-link later mentions on the same page, don't link a page to itself, and link at the page level rather than to an anchor. Use the surrounding prose as the link text instead of inventing new phrasing just to create a link. - Always use a relative path (
[samples](elements/samples)) for links within the same docs instance -- never an absolute/docs/...one; see This Documentation for why (and a gotcha with index pages). Absolute/docs/<instance>/...paths are only for links that cross into a different docs instance (e.g. a LabIMotion page linking to an ELN page), where a relative path can't reach.
Terms
- Refer to the Chemotion Electronic Lab Notebook as
Chemotion ELN. - Refer to the Chemotion spectra editor for analytical data as
ChemSpectra. - Refer to the repository as
Chemotion Repository. - Refer to the generic-module extension as
Chemotion LabIMotion(orLabIMotionon second mention within a page).
Titles
- Capitalize only the first word (except for names or abbreviations).
- Use all low caps starting at header level 4 (
####).
Sidebar labels
- Capitalize only the first word (except for names or abbreviations).
Lists
- Capitalize the first word of each list entry.
- Use regular punctuation within list entries.
Tables
- Do not capitalize words inside tables.