DITA 1.3 vs freeform for a first task: the one-day spike test

The method has two timed parts: a 60-minute planning session in which the team names its reuse points and output formats in advance, followed by the one-day spike that drafts the same procedure both ways and counts reused fragments.

The test uses a one-day spike with a 5-topic procedure and counts reused fragments across two or more outputs.

How DITA 1.3 Structures a First Task

DITA 1.3 structures a first task by requiring the author to classify content into one of three base topic types: task, concept, or reference. A task carries the procedure, a concept carries the background a reader needs before acting, and a reference carries lookup material such as parameters or tables. Treat this as a schema rule to verify, not a vendor promise: check the current OASIS DITA 1.3 specification at docs.oasis-open.org, because toolkits and editors often implement only a subset of the standard.

The mechanism worth testing in your spike is the content model inside a task. A <task> topic can contain <steps>, and a step can contain nested <substeps>, but it should not accept a free paragraph as a direct child of <step>. Write one deliberately malformed task with a paragraph placed directly inside a step, then run your validator, whether that is an XML schema check or DITA-OT lint. If the validator does not flag the violation, your toolchain is not enforcing the constraint you are evaluating, and any later comparison of tooling is measuring convenience rather than structure.

Specialization is how DITA narrows those base types for a project. A specialized task can restrict or rename elements and attributes, so a first-time author is not writing against generic DITA; they are writing against the project's specialized schema. Before the spike, obtain that schema or DTD and validate against it. If your team has no specialization, use the base types, but still run the same validator check so the first draft is constrained by something explicit rather than by habit.

Key-based content reuse is the other structural mechanism to test. In a DITA map, a key can name a shared fragment, and a task can reference that fragment by key instead of by file path. During the spike, define one key and reference it from two outputs. Record whether resolution succeeds, whether the same fragment appears unchanged, and whether a missing key produces a clear validation or build error. That result tells you whether reuse is actually governed by the structure or by manual copying.

Use a simple pass rule for the first task: the validator must reject the malformed paragraph-in-step example and resolve the shared key in both outputs. If both checks pass, DITA 1.3's constraints are doing work you can name in advance. If either fails, the constraint is not yet operational, and a freeform draft may be the safer first task until the schema or map is fixed.

The Evidence: What Independent Sources Support

This section audits the available sources rather than repeating product claims: no independent head-to-head study comparing DITA 1.3 with a freeform baseline for first-task completion time appears in the retrieved grounding. Consequently, any percentage you encounter—especially the pattern common in vendor case studies—must be traced to a named, reproducible method before it informs a choice. A figure without that trail is not evidence; it is a marketing artifact.

The primary evidence for what the standard mandates is the OASIS DITA Technical Committee's DITA 1.3 specification and errata. Treat vendor whitepapers, tool screenshots, and blog posts as marketing until they cite that specification or its errata and show the method behind any number. Conformance claims and productivity claims are different objects: the former can be checked against the standard, while the latter require a study design.

Use this named verification protocol, the OASIS-first citation audit, for every quoted result: (1) write the claim and figure exactly as quoted; (2) name the source and its date; (3) check whether the source is the OASIS DITA 1.3 specification or errata, or explicitly cites them; (4) check whether it defines the task, the freeform baseline, the sample, and the measurement procedure; (5) if any element is missing, mark the claim unverified and exclude it from the decision memo. The protocol does not require a new benchmark; it requires that every benchmark be inspectable.

A source that cites the OASIS specification but lacks a method can support statements about conformance, not about completion time. A source that reports a method but does not cite the OASIS specification can support a local observation, not a claim about what DITA 1.3 mandates. Only when both conditions are met should the result be treated as transferable evidence for another team's first task.

The practical rule is to keep two lists while evaluating options: verified claims that survive the audit and unverified claims that do not. The absence of a head-to-head benchmark does not make freeform the default; it means the decision must be grounded in named reuse points, named output formats, and your own inspectable spike rather than in an untraceable percentage.

DITA 1.3 vs Freeform: A Scored Comparison

This comparison scores DITA 1.3 against a freeform baseline on five criteria plus one tiebreaker. It assumes you have already named the reuse points and output formats for the task; if you have not, treat the table as a checklist for your spike rather than a verdict. The scores are criteria-level, not vendor-level, and they assume the 2026 tooling landscape described in the checks.

Freeform wins the first criterion because the first author can draft without deciding how content will be classified or reused. DITA 1.3 wins the next two only when the reuse points and output formats are already named; if those names change during the spike, the DITA advantage shrinks and the freeform draft remains easier to revise.

The tiebreaker is validator enforcement. Run one deliberately malformed draft through both pipelines: a DITA build should stop on a schema error, while a freeform draft can pass formatting checks and still carry the structural mistake into review. Use that result as the deciding check when outputs are generated automatically.

Apply the table to your own spike, not to a generic score. DITA 1.3 is the better first-task choice when it wins reuse enforcement, multi-format output, and validator enforcement and your named reuse points survive the draft unchanged; otherwise, freeform is the safer first task and DITA can be reconsidered after the reuse map stabilizes.

Costs and Numbers That Matter

Measure cost in hours your team can observe, not in license or tooling claims. The three units are hours to first valid draft, hours per format added later, and hours of reviewer correction. Record each from your own spike, because the available sources provides no external cost benchmark for either approach; an internal baseline is the only defensible comparison you can defend in a review.

Price the wrong choice in both directions. Choosing freeform when reuse is needed means paying per-format conversion later; estimate that by timing one manual conversion of your spike output. Choosing DITA when reuse is absent means paying schema learning and authoring constraint without the offsetting savings that reuse would provide.

The real cost driver is reviewer and rework hours. Count corrections caused by duplicated edits, inconsistent steps, and format drift across outputs. If those hours dominate, the approach that reduces duplicated edits is cheaper even if its first draft is slower.

Run both versions against the same procedure and output set, then compare the three cost units priced above. If the hours to first valid draft are not recovered by lower per-format and reviewer-correction hours for your planned outputs, freeform is the cheaper choice for this task; otherwise DITA's conversion savings may justify its schema cost.

Keep the estimate honest by using your own timings rather than imported benchmarks. Re-run the comparison whenever the output list, review process, or reuse points change, because the cost balance moves with them.

What This Evidence Does Not Establish

The spike is a first-task test, not a maintainability forecast. Drafting the same five-topic procedure both ways can show whether reuse is visible now, but it is not evidence that DITA's constraint pays off at five hundred topics; log that as an explicit unknown and set a three-month revisit checkpoint before treating the spike as a commitment.

The 3-fragment threshold rule counts only fragments reused across two or more outputs, and it breaks when regulated content carries per-output variance. A fragment that looks shared but changes wording, conditions, or warnings by output is not one reusable unit; check each candidate for exact-text identity before adding it to the count.

The exact-text check should include punctuation, variables, and conditional phrases, not just the visible sentence. If one output adds a jurisdiction-specific clause, split the candidate into two fragments and count neither unless the shared core is identical in both outputs.

The rule still wins despite variance when the differing material is isolated into a named conditional branch and the shared core remains identical. In that case, count the core once and track the branch separately rather than discarding the reuse.

Keep the unknowns explicit: the spike is not evidence for long-term maintainability, and the threshold is not reliable when a count mixes near-matches with exact matches. Re-run the same check at the three-month checkpoint, using the same five-topic baseline, before expanding the DITA scope.

A low fragment count is not a verdict on freeform's cost or speed; the spike measures reuse only. If the count is below three, record the missing reuse as a requirement gap and decide whether the outputs can be narrowed before choosing an approach.

One Procedure, Both Pipelines

Run the spike with one five-step API-key onboarding procedure, two target outputs (web help and PDF), one author, and one working day. Draft the same procedure in both pipelines, then record four checkpoints for each: hours to first valid draft, validator errors per draft, reviewer edits per topic, and fragments that appear verbatim in both outputs. A valid draft is one that renders in both target outputs without manual repair; if your pipeline has no validator, record the repair steps instead of errors.

Use a concrete procedure such as: create the account, generate the API key, set the environment variable, make a test request, and rotate the key. In the worked example, steps 2 through 4 recur unchanged in a troubleshooting topic, so the worksheet records three distinct fragments, not three occurrences of one fragment. The count is distinct fragments reused across two or more outputs or topics; repeated boilerplate inside one output does not count.

Count reviewer edits per topic as changed words or changed steps, not as comments. If reviewers rewrite a step in one pipeline but only adjust wording in the other, note which step changed so the edit count reflects structural work rather than preference.

Apply the rule only after the worksheet is complete: the worked example fires for DITA when three distinct fragments are named before drafting; if your count is lower, or the reuse points were discovered only after drafting, freeform may be the safer first task. The worksheet does not prove DITA is faster; it only shows whether your content has the named reuse points the thesis requires.

Keep the comparison honest by holding author, procedure, and review criteria constant across both drafts. If one pipeline needs extra setup time, record it in the hours checkpoint rather than absorbing it into editing time. The spike is a decision aid for one task, not a permanent platform choice.

Worked Example: Run the Numbers

Illustration only, not measured data: scenario = a five-topic installation procedure; party = a two-author documentation team; dates = a one-day spike in 2026; outputs = HTML, PDF, and release notes. The spike drafts the same five topics both freeform and structured, then counts distinct content fragments reused across two or more outputs. A fragment is a self-contained block, not a whole topic, so one topic can contribute zero, one, or several fragments.

Step 1, freeform count. In the illustration, three fragments recur: a safety warning in all three outputs, a prerequisite list in HTML and PDF, and a troubleshooting table in PDF and release notes. Topics four and five have no recurring fragment. Distinct fragments reused across two or more outputs = 3. This is a discovery count made after drafting, not a plan made before drafting.

Step 2, structured count. The same three fragments are named as reuse points before drafting, so the structured draft contains three references to shared components rather than three copied blocks. The count of named reuse points is 3; the count of outputs is 3; no additional recurring fragment is discovered during drafting. The arithmetic check is 3 named points = 3 discovered fragments, with 0 unmatched fragments.

Step 3, comparison. Freeform reuse is implicit and must be found by rereading; structured reuse is explicit because the three points were named in advance. For this illustration, the structured draft has 3 named reuse points against 3 discovered recurring fragments, so the two counts match. If the counts did not match, the spike would show that the team could not name its reuse points in advance.

Winner for this illustration: structured authoring, because every recurring fragment was named before drafting and appears in at least two of three outputs. Break-even trigger: run the spike; if it finds at least 3 distinct fragments reused across at least 2 outputs, choose structured authoring for that task; if it finds fewer than 3, stay freeform. This trigger is a decision rule for the example, not a universal claim about effort or tooling.

Decision Rules for Your First Task

Apply these four rules only to a completed spike worksheet; an unmeasured estimate is not a substitute for the one-day test. The worksheet should record distinct fragments, not repeated mentions of the same wording. Keep the worksheet with the project notes so the next review can see the counted fragments, the outputs they appeared in, and the date of the spike.

If the worksheet shows three or more verbatim fragments reused across two or more outputs, choose DITA 1.3 for the first task. Key-based reuse and specialization should already have been tested in the spike as described above; for the first production task, limit scope to base task topics and adopt those mechanisms fully only once the reuse map stabilizes at the three-month revisit checkpoint.

If the worksheet shows zero to two such fragments and HTML is the only planned output, stay freeform and revisit the decision when a second output format or a second product line appears.

If the team cannot commit one author-day to the spike, do not adopt DITA yet; the unmeasured migration cost is the single largest failure risk in this decision.

Count a fragment only when the wording is verbatim and it appears in at least two finished drafts. If the count is exactly three, verify each match line by line; paraphrased or shortened wording does not count. If a second output is planned but not yet drafted, finish that draft before applying any rule. Notes about likely future reuse belong in a separate list and do not enter the threshold.

When a later project adds an output format or product line, rerun the same five-topic spike and recount before changing the earlier decision. Treat the new worksheet as the current decision record, not as an amendment to the old one. The rules are ordered by evidence: fragment count first, output count second, and available author time third; if two rules appear to conflict, run the missing part of the spike rather than choosing the more convenient option.

Frequently Asked Questions

Under what condition does DITA 1.3 beat freeform for a first task?

DITA 1.3 beats freeform only when reuse points and output formats are named in advance.

What is the spike's decision check?

The spike's decision check is the count of distinct content fragments reused across two or more outputs.

How is the 60-minute method structured?

The method has two timed parts: a 60-minute planning session in which the team names its reuse points and output formats in advance, followed by the one-day spike that drafts the same procedure both ways and counts reused fragments.

What size procedure does the test use?

The test uses a one-day spike with a 5-topic procedure and counts reused fragments across two or more outputs.

What base topic types must content be classified into?

DITA 1.3 structures a first task by requiring the author to classify content into one of three base topic types: task, concept, or reference.

What does each base topic type carry?

A task carries the procedure, a concept carries the background a reader needs before acting, and a reference carries lookup material such as parameters or tables.

Quick answers

Also worth reading: Software docs compared: Darwin Information Typing Architecture (DITA) vs Mintlify 32% 2026: Software docs compared: Darwin Information · How to write docs 2026: Darwin Information Typing Architecture (DITA) vs Freeform 31% cut: How to write docs 2026: · Writing sprint docs: Darwin Information Typing Architecture (DITA) 32% cut vs mandate: Writing sprint docs: Darwin Information