Writing rules

The writing rules are the checkable part of FTL. They are derived from ASD-STE100 and software engineering conventions, but they are written by Fenexity.

The writing rules are the checkable part of FTL. They are Fenexity rules derived from ASD-STE100, software-engineering conventions, and normative requirements language (RFC 2119 / RFC 8174), not a reproduction of any external standard. FTL's 31 writing rules are split into authoring rules (FTL-Axx) and transformation rules (FTL-Txx).

authoring

Authoring rules

Authoring rules constrain how new technical information is expressed when writing a README, architecture document, requirement, runbook, or similar content.

When a concept has an established preferred term, use it instead of an alternative that means the same thing.

Avoid

charger / charging device / charging point

Prefer

EVSE (when that is the intended concept)

Check the FTL terminology data before choosing a term.

Linguistic variation without semantic distinction increases ambiguity. Linguistic variation that represents a real semantic distinction must be preserved. Do not introduce different words merely for stylistic variety when the meaning is intended to remain identical.

Avoid

The documentation calls the same operation start, begin, and commence only for stylistic variation.

Prefer

Use start consistently for that operation.

Different words are permitted and required when they represent different concepts, states, actions, or transitions. For example, initialize and start can be separate terms when initialization and execution are separate system transitions. This rule prohibits variation only when the different words do not represent a real semantic distinction. For ordinary general-language words (for example start vs begin, use vs utilize), consult the general-language vocabulary at /api/latest/general-language.json and the General Language page.

State who or what performs an action. Do not rely on implicit or ambiguous subjects.

Avoid

It should then be updated.

Prefer

The charging service SHOULD update the charging plan.

When a condition governs an action, state the condition first, then the action.

Avoid

Enforce the local site power limit when the cloud connection is unavailable.

Prefer

If the cloud connection is unavailable, the edge controller MUST enforce the local site power limit.

Express actions as verbs. Avoid nominalization that obscures who does what.

Avoid

The execution of validation occurs after initialization.

Prefer

The service validates the configuration after it initializes.

Review it, this, that, they, former, and latter when more than one referent is possible. Repeat the noun where needed.

Avoid

The EVSE and the vehicle are connected. It starts charging.

Prefer

The EVSE and the vehicle are connected. The vehicle starts charging.

The rewrite must keep the intended meaning.

Separate normative requirements from explanation. Do not bury MUST, SHOULD, or MAY statements in descriptive text.

Avoid more robust, real-time, efficient, fast, reliable unless the relevant criterion is defined. State the measurable requirement.

Avoid

The system reports faults reliably.

Prefer

The system reports each detected fault within 10 s after detection.

Do not invent the criterion. If the source does not define what reliable means, flag the missing semantics and ask which property is intended (latency, availability, completeness, ...) before writing a measurable statement.

Do not use a bare number where the physical quantity or unit is necessary for interpretation.

Avoid

Set the limit to 50.

Prefer

Set the site power limit to 50 kW.

The rewrite is only valid if the source establishes that the limit is a site power limit in kW. Otherwise flag that the quantity and unit are undefined.

Do not present an estimate as a measurement or a derived quantity as a direct physical measurement. Label the semantic type when it matters.

Avoid

The battery is at 80%.

Prefer

The estimated State of Charge is 80%.

SoC is not the same semantic type as measured terminal voltage.

In normative Fenexity technical documents, use MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY with the meanings defined in RFC 2119 and RFC 8174.

Uppercase normative terms have normative meaning only in documents or sections that explicitly adopt this convention.

Use OCPP, IEC, VDV, or software-engineering terminology where it accurately expresses the concept. Invent company terms only when no established term fits.

Avoid

charger for EVSE

Prefer

EVSE

Domain-specific technical nouns and verbs are permitted; they should come from the glossary, not from improvisation.

State who or what performs an action in active voice when the actor matters. Use passive voice only when the actor is unknown, irrelevant, or intentionally concealed.

Avoid

The site power limit is enforced by the edge controller.

Prefer

The edge controller enforces the site power limit.

Passive voice is acceptable when the actor is unknown or irrelevant, for example in an error description such as the connection was lost. In requirements, architecture records, and runbooks, name the actor in active voice.

Use a direct verb when one expresses the action clearly. Avoid phrases such as perform the validation of, make a determination, or give consideration to where the simple verb is available.

Avoid

The service performs the validation of the configuration.

Prefer

The service validates the configuration.

Keep a complex construction when it names a real composite operation with no simple verb, for example perform a health check. Do not force a single verb where it would distort the meaning.

When several nouns are joined without clear relationships, restructure the phrase using prepositions, possessives, clauses, or explicit relationships. Do not rewrite established technical terms that have a defined meaning.

Avoid

charging station site power limit update handling logic

Prefer

logic that handles updates to the site power limit for the charging station

Established technical terms such as State of Charge and Charging Station Management System keep their conventional form. Apply this rule to ad hoc noun chains, not to defined terms from the FTL terminology data.

Keep one primary proposition per sentence where practical. Split a long sentence that carries several independent claims into separate sentences or a list.

Avoid

The dispatcher confirms the vehicle and the charger starts and then the session is logged.

Prefer

The dispatcher confirms the vehicle. The charger starts. The system logs the session.

This rule does not impose a sentence-length limit. Compound sentences are acceptable when the claims are tightly coupled, such as a cause and its immediate effect.

When a sentence would otherwise contain several complex coordinated items, use a vertical list so each item stands alone and has a parallel construction.

Avoid

The deployment verifies the certificates, checks that the charging points respond, and then confirms that the meters report values, and it writes all results to the log.

Prefer

The deployment performs these steps:
- verifies the certificates;
- checks that the charging points respond;
- confirms that the meters report values;
- writes the results to the log.

Use vertical lists for genuine enumeration with complex items. Do not force short, simple enumerations into lists when inline phrasing is clearer.

Give each paragraph one primary topic. State the topic early and keep related information together.

Avoid

This section describes the authentication flow. The EVSE also supports energy metering, and the CSMS stores transaction records.

Prefer

This section describes the authentication flow. The EVSE authenticates the driver before energy transfer begins.

Split a paragraph that covers several unrelated topics. This rule targets paragraph structure, not sentence length.

Keep step-by-step instructions distinct from descriptive or explanatory information. Put instructions in their own section or list; do not bury steps inside explanatory paragraphs.

Avoid

To recover from a failed update, and this is because the previous image remains valid, restart the service and then check the log.

Prefer

To recover from a failed update:
1. Restart the service.
2. Check the log.

The previous image remains valid after a failed update.

This complements FTL-A07, which separates normative requirements from explanation. Here the separation is between instructions (steps) and description (context or rationale).

Express one normative obligation per requirement where practical. Split a requirement that combines several unrelated obligations into separate statements.

Avoid

The system MUST authenticate the user and MUST store the audit record and MUST return a status code.

Prefer

The system MUST authenticate the user.
The system MUST store the audit record.
The system MUST return a status code.

Keep a single statement when the obligations describe one atomic operation. This rule complements FTL-A11 (RFC normative terms) and is not a fixed requirement-count limit.

When the meaning of one statement depends on another, say how they are related. Use causal, conditional, contrastive, or sequential connectors (because, therefore, however, if, then, unless) where the relationship is not already obvious.

Avoid

The request failed. The connection was unavailable.

Prefer

The request failed because the connection was unavailable.

Adjacent sentences imply adjacency, not causality. Add a connector only when the source establishes the relationship; do not invent one. This rule complements FTL-A16 (one primary proposition per sentence).

When an action or condition can cause harm, identify the type of risk and state the consequence of getting it wrong. Distinguish human safety, equipment risk, data-loss risk, security risk, and service-availability risk rather than using a generic warning.

Avoid

Do not disable the safety relay.

Prefer

If you disable the safety relay, the vehicle can remain connected to live charging current.

Never say merely "Do not do X" when the consequence is known; state it. This broadens the safety-instruction principle beyond physical safety to security, irreversible data changes, and service interruption. It complements FTL-A04 (state the condition before the action).

Do not use capacity as an unqualified generic term. Qualify the resource, dimension, unit, and relevant time horizon or operating condition. Use capacity for the maximum quantity or rate possible under stated conditions, allocation for the portion reserved for a consumer or purpose, availability for whether the resource can be used during a stated period, utilization for the portion currently used, readiness for whether operation can begin, and capability for whether the system can perform the function at all.

Avoid

capacity
available_capacity
maximum_capacity

Prefer

site_connection_capacity_kw
available_charging_power_kw
battery_energy_capacity_kwh
daily_depot_vehicle_capacity
support_case_throughput_per_hour

Capacity is multidimensional. In an electrical context, connection capacity, rated power, available power, charging capacity, battery energy capacity, and operational capacity are different concepts. In a business or operational context, capacity can describe vehicles per day, transactions per second, staff hours per week, depot parking spaces, support cases per shift, or budget for a programme. Preserve these distinctions. If the meaning is not already explicit, ask: Capacity of what? Which dimension applies (power, energy, volume, throughput, people, money, or space)? Is the value a limit, allocation, remaining amount, or current operating value? What unit and time horizon apply? Which constraints or operating conditions define it?

When a term can refer to logistics and electric charging, qualify the resource or operation before using it. Use batch for a logistics Charge, cargo for transported goods, loading operation for placing cargo on a vehicle, and charging or charge the battery for electrical energy transfer. Do not use chargen as a canonical German expression for electric charging. Do not use bare Charge, Ladung, Laden, Ladevorgang, loading, or charging when both domains are possible.

Avoid

Charge
Ladung
Laden
Ladevorgang
chargen

Prefer

batch
cargo
loading operation
electric charging
charge the battery

The German expressions Charge, Ladung, Laden, and Ladevorgang are context-dependent. Preserve standard-specific terminology when it is quoted, but qualify the concept in new or mixed-domain prose so that logistics batches, transported goods, cargo loading, and electrical energy transfer remain distinct.

transformation

Transformation rules

Transformation rules additionally constrain how existing information may be changed when summarizing, translating, restructuring, normalizing, extracting, or transcribing source material. They have stronger source-fidelity requirements.

Do not convert lowercase or ordinary-language modality into uppercase RFC modality unless the source already establishes the corresponding normative meaning or an authorized decision introduces that requirement. Keep the modality of the source.

Avoid

The service could retry. becomes The service MAY retry.

Prefer

The service could retry. (preserve the source modality; could does not imply normative permission)

Lowercase could can express possibility, capability, a hypothetical case, or a tentative option. Ordinary lowercase should does not automatically mean RFC uppercase SHOULD. Only the source or an explicit authorized decision can introduce normative force.

Do not strengthen or weaken the uncertainty expressed by the source. Keep estimates as estimates, possibilities as possibilities, and proposals as proposals.

Avoid

The battery is at 80% (source: estimate) becomes The battery is at 80%.

Prefer

The estimated State of Charge is 80%.

Complements FTL-T01, which covers modality (requirement force); this rule covers epistemic status (estimate vs measurement, possible vs certain).

A requested mechanism is not automatically the underlying requirement. Record the intended outcome and the proposed mechanism separately when they differ.

When the source does not specify a quantity, a unit, or a criterion, do not invent one. Expose the missing value and request it.

Avoid

The battery has a capacity of 400 becomes The battery has a nominal energy capacity of 400 kWh.

Prefer

The battery has a capacity of 400. (quantity type and unit are unspecified)

Transformation counterpart of FTL-A08 and FTL-A09.

If a term has multiple plausible technical meanings in the context, ask for clarification or explicitly state the interpretation you are using.

Avoid

The PLC must be configured.

Prefer

The Programmable Logic Controller must be configured. (state the intended meaning)

When normalizing, translating, or mapping to FTL terminology, keep the source term if a substitute would change the meaning. Record the mapping instead of silently renaming.

Avoid

Mapping charge point to charging station without noting the version difference.

Prefer

Record charge point (OCPP 1.6) as a legacy alias of charging station.

Transformation counterpart of FTL-A01 and FTL-A12.

When source material uses capacity, preserve the source wording until the resource, dimension, unit, time horizon, operating condition, and semantic role are known. Do not silently rewrite capacity as availability, readiness, allocation, utilization, or capability, and do not silently assign a limit or a current value. Ask for clarification or state the interpretation explicitly; if the source does not resolve the ambiguity, keep the missing semantics visible.

Avoid

The battery has a capacity of 400.

Prefer

The battery has a capacity of 400. (The capacity dimension and unit are unspecified; clarify before rewriting.)

This rule preserves source fidelity while applying P9. A term such as capacity may be correct in the source but incomplete for a technical rewrite. Do not collapse connection capacity, rated power, available power, charging capacity, battery energy capacity, or operational capacity into one generic concept.

Writing rules

Authoring rules

Use the preferred technical term

Do not introduce synonyms without semantic purpose

Use explicit subjects

State the condition before the action

Use concrete verbs

Avoid vague referents

Do not hide requirements in descriptive prose

Use measurable properties instead of vague adjectives

Keep units explicit

Distinguish measurements, derived quantities, and estimates

Use RFC normative terms consistently

Prefer established domain terminology

Prefer active voice when the actor matters

Avoid unnecessarily complex verb constructions

Restructure ambiguous noun clusters

Use one primary proposition per sentence where practical

Use vertical lists for complex coordinated items

Use one primary topic per paragraph

Separate procedural instructions from descriptive information

Use one normative obligation per requirement where practical

Express logical relationships explicitly

Identify the risk and state the consequence

Qualify capacity by its semantic dimensions

Resolve logistics and charging homographs

Transformation rules

Preserve source modality

Preserve source uncertainty

Preserve intent separately from implementation

Do not invent missing quantitative criteria

Flag ambiguity instead of silently guessing

Preserve source terminology when normalization or translation would change meaning

Resolve capacity before transformation