Style Guide

This page defines the writing, capitalization, and interface terminology standards for the Lowgile documentation.

1. UI Element Capitalization

Use UI capitalization only when the text matches what users see on-screen.

Example	Rule	Correct Usage
Button names	Capitalize each word	Click Save
Menu or tab names	Match on-screen label	Open the Design tab
Generic interface areas	Lowercase unless labeled in UI	“in the main navigation sidebar”
Keyboard keys	Uppercase	Press Ctrl + S (or Cmd + S on macOS)

Example:

Click the Design button in the main navigation sidebar.
(lowercase because the sidebar isn’t literally labeled “Main Navigation Sidebar.”)

2. General Writing Style

Use present tense and active voice.
- ✅ “Click the Save button.”
- ❌ “The Save button should be clicked.”
Write clear, step-based sentences for instructions.
- ✅ “Select the module, then click Configure.”
- ❌ “Once selected, configuration may proceed.”
Avoid redundant text. Do not repeat information already conveyed by headings, diagrams, tables, or preceding sections.
Prefer concise, action-oriented language.

2.1. Standard technical phrasing

Use standard technical phrasing that aligns with established developer documentation conventions.

Preferred	Avoid
Leave all other properties at their default values.	Leave all other properties as their default values.
Leave the remaining settings at their default values.	Leave the remaining settings as their default values.

Use at their default values when instructing users not to modify configuration settings. This phrasing is the standard convention used throughout Google, Microsoft, Oracle, and other enterprise technical documentation.

2.2. Reader-focused language

Use second person (you and your) when the reader is the actor, but do not add second-person pronouns when the sentence is clearer without them.

In explanatory prose, use you or your when addressing the reader directly.
- ✅ “You can copy a Business Object within the same app or import it into another app.”
- ❌ “A Business Object can be copied within the same app or imported into another app.”
In procedural steps, use imperative verbs without you.
- ✅ “Open the Design area.”
- ✅ “Select the Business Object.”
- ❌ “You should open the Design area.”
- ❌ “You can then select the Business Object.”
When describing Lowgile behaviour, make Lowgile or the relevant component or object the subject.
- ✅ “Lowgile imports the Business Object definition.”
- ❌ “You will see the Business Object definition being imported.”
When describing a technical state or result, make the relevant technical object the subject.
- ✅ “The copied Business Object retains its configured properties.”
- ❌ “You will have a copied Business Object with its configured properties.”

Avoid repeatedly beginning sentences or paragraphs with phrases such as “You can,” “You will,” or “You should” solely to maintain second-person voice. Use second person when it identifies the reader as the actor; otherwise, use the clearest grammatical subject.

3. Terminology and Formatting

Element	Style
Module, Entity, Screen, Process	Capitalize when referring to Lowgile concepts
purchasing app / application	lowercase unless it’s part of a title
filenames and paths	Use backticks: `src/styles/callouts.css`
product name	Always Lowgile Studio

App versus module

App is the preferred user-facing term for a functional solution built with Lowgile Studio. Although developers create modules within a Lowgile application, documentation should generally refer to the overall solution as an app. Use module only when discussing the underlying platform architecture or module-specific features.

Use app throughout tutorials, conceptual documentation, and marketing-oriented content because it reflects the user-facing terminology of the Lowgile platform.
Use module only when referring to the technical implementation inside Lowgile Studio.
When both terms are needed, introduce the relationship once, then continue using app unless the discussion specifically concerns modules.

4. Callouts

Use callouts to highlight key information:

Use callouts selectively. Do not place essential procedural steps only inside a callout.
Choose the most specific callout type available. For example, use troubleshoot for a known error rather than the more general note type.
Do not use multiple callouts to repeat the same information in different forms.
Use caution for recoverable configuration or implementation risks. Reserve danger for severe consequences such as data loss, security exposure, or irreversible changes.
Use tip, insight, and note for different purposes:
- tip provides an optional improvement or shortcut.
- insight explains useful context or implications.
- note provides supplementary factual information.
Use lesson to reinforce a concept during a tutorial. Use keytakeaway to close a section by identifying its central conclusion.

Type	Title	Purpose
`why`	Why	Explaining the reason behind a step, design decision, or platform behaviour.
`insight`	Insight	Adding useful context that improves understanding but is not required to complete the task.
`principle`	Principle	Stating a reusable design, architecture, or implementation principle.
`feedback`	Feedback	Presenting user, reviewer, or stakeholder feedback relevant to the documented decision or workflow.
`outcome`	Outcome	Describing the expected result after completing a procedure or configuration.
`attention`	Attention	Drawing attention to important information that could otherwise be overlooked.
`caution`	Caution	Warning about an action that could cause an error, an incorrect configuration, or unintended behaviour.
`danger`	Danger	Warning about an action that could cause data loss, security exposure, or another serious consequence.
`troubleshoot`	Troubleshooting Tip	Providing a targeted solution to a known error, symptom, or failure condition.
`helper`	Editor Help	Explaining behaviour, controls, shortcuts, or guidance provided by a Lowgile editor.
`lesson`	Key Lesson	Reinforcing an important concept that the reader should understand before continuing.
`tip`	Tip	Offering an optional shortcut, efficiency improvement, or easier way to complete a task.
`note`	Note	Providing supplementary information that does not fit naturally into the main procedure.
`action`	Action	Identifying a required follow-up action outside the immediate procedure.
`advanced`	Advanced	Separating optional or complex information intended for experienced users.
`keytakeaway`	Key Takeaway	Summarising the most important point from a section or completed procedure.

5. Avoiding Redundant Explanations in Documentation

When structuring instructional content (especially in multi-step guides such as “Build Your First App”), avoid repeating the same conceptual explanation in adjacent sections.

Recommended Approach

Use the introduction of a page or step to define any key concepts the reader needs (e.g., static entities, transactional entities, workflows, data models).
Use the overview section to give a concise, high‑level framing—typically one or two sentences that set context.
Allow diagrams and figure captions to do the explanatory heavy lifting rather than repeating their contents in prose.
Keep subsequent sections purpose‑driven:
- Introduce only what the user will create or do next.
- Avoid restating entity definitions, relationships, or terminology that already appeared in the introduction.

Example

Instead of:
A Data Model Overview section that restates:

There are two static and four transactional entities
What each entity type is used for
How the Server Data Store connects them

Use:

A single high‑level sentence setting context
The diagram and its caption
A table listing the entities without duplicated narrative

This results in streamlined, scannable documentation with no repeated explanations.

6. Heading Capitalization

Use sentence case for all headings, including H1s

Only capitalize:

the first word,
proper nouns, and
product names