Chapter 6: The README — Your User Guide, Your Marketplace Listing, Your Sales Pitch

"You have built something extraordinary. Now you need to explain it to the person who has never heard of you, found your domain at 10pm, and needs to decide in three minutes whether it is worth their time."

The Document That Does Everything

Every other artifact in your domain package serves the platform or the templates. The CSV files feed the data engine. The domain-config.json configures the server. The generator script produces the Word files. These are technical artifacts that users never directly see.

The README is different. It is the only document in your domain package that speaks directly to a human being. And it has to do three completely different jobs simultaneously.

Job One: Marketplace Listing. Before anyone downloads your domain, they read the README. It is your product page, your brochure, your 30-second elevator pitch. A prospective buyer who has never heard of your domain scans the first two paragraphs and decides whether to keep reading or click away. If your README opens with technical jargon or a table of column definitions, they click away. If it opens with a clear description of the problem it solves and the person it serves, they keep reading.

Job Two: User Guide. After someone downloads your domain, the README is the first thing they open. It tells them how to load the domain, how to select a template, what each of the 20 templates does, and how to get started with their own data. A confused user who cannot figure out how to generate their first document in five minutes is a user who uninstalls and moves on. A clear, confident quick-start guide is the difference between a subscriber and a refund request.

Job Three: Reference Manual. After someone has been using your domain for a month, the README is where they return when they hit an unfamiliar scenario, want to understand a specific template better, or need to customize the data structure. It needs to be thorough enough to answer questions you did not anticipate, written in a way that experienced users can navigate quickly without re-reading content they already know.

Three jobs. One document. This chapter shows you how to write it.

The README Structure

A great domain README has nine sections, in this order. The order is not arbitrary — it reflects the sequence in which different types of readers need different kinds of information.

1. The Hook          — Who this is for and what problem it solves (readers decide here)
2. What's Included   — A quick inventory of the domain's contents
3. Quick Start       — From download to first document in five minutes
4. The 20 Templates  — Complete catalog, organized by category
5. Data Structure    — The tables, their fields, their relationships
6. Sample Data       — What the sample data covers and why
7. Customization     — How to replace sample data with real organizational data
8. Advanced Usage    — Connecting live data sources, extending the domain
9. Troubleshooting   — The ten most common problems and their solutions

We will write each section for the legal services domain, with commentary on the decisions behind each one.

Section 1: The Hook

The hook is the most important section in the README. It must accomplish three things in the space of three to five sentences: identify the target user precisely, name the specific problem they face, and state clearly what this domain does about it.

Notice what the hook does not do: it does not describe the technology, it does not list features, it does not use the word "seamless," and it does not open with the name of the product. It opens with the user.

Here is the hook for the legal services domain:

# Legal Services Domain for Data Publisher for Word

Law firms run on documents. Engagement letters, client invoices, court preparation
sheets, retainer agreements, deadline calendars, matter status reports — the average
attorney generates dozens of documents every week, most of them variations on
documents they have generated hundreds of times before.

The Legal Services Domain eliminates that repetition entirely. Connect your client
and matter data once, and generate any of 20 professionally formatted legal documents
in seconds — branded to your firm, addressed to your client, populated with the exact
details of the specific matter.

Built for law firms from solo practitioners to mid-size general practices. No
template design required. No mail merge configuration. No document formatting.
Just your data, and the documents it should be producing automatically.

Why this hook works: The first sentence establishes domain credibility — it names specific documents that real attorneys generate, showing immediately that this was built by someone who understands the industry. The second paragraph states the value proposition with precision: "Connect your data once, generate any of 20 documents in seconds." The third paragraph names the target user range and dispels the three most common objections ("is this complicated to set up?") in one sentence.

A reader who is an attorney or a paralegal reads this and thinks: this was made for me. That thought is the entire goal of the hook.

Section 2: What's Included

This section is a quick inventory. Its purpose is to give the reader a complete picture of the domain package before they dive into the details. Keep it scannable — this is one of the few places in the README where a structured list is the right format.

## What's Included

**Data Structure:** 10 relational tables covering the complete operational data of
a law firm — firms, practice areas, clients, attorneys, matters, hearings,
deadlines, billing entries, invoices, and filed documents.

**Sample Data:** 81 realistic records across all 10 tables, including 3 law firms,
10 clients (individual and entity), 9 attorneys across three seniority levels,
10 active and closed matters across 6 practice areas, and complete financial records
with all payment scenarios represented.

**20 Document Templates** organized across 5 categories:
- Client Communications (5 templates)
- Legal & Compliance (4 templates)
- Court & Proceedings (4 templates)
- Operational (4 templates)
- Administrative & Financial / Marketing (3 templates)

**Documentation:** This guide, a complete schema reference, and a data sources
integration guide for connecting live firm data.

**Generator Script:** The complete JavaScript source used to create all 20 templates
— modify and regenerate for your own customizations.

The generator script mention is deliberate. Including it in the "What's Included" section signals to developer-oriented readers that this domain is open, forkable, and customizable at the source level. That signal — you can see exactly how this was built and change anything you want — is one of the most powerful trust-builders in an open marketplace.

Section 3: Quick Start

The Quick Start is the section that converts a download into a subscriber. It must get a new user from zero to their first generated document in five steps or fewer, with each step taking less than a minute.

This section requires ruthless editing. Every word that is not necessary to get the user to their first document is a word that delays them getting there. No background. No theory. No "before we begin." Just the steps.

## Quick Start — Your First Document in 5 Minutes

**Step 1: Load the domain in Data Publisher**
Open Microsoft Word with the Data Publisher add-in active. Go to the
**Data** tab and choose **Data Sets**. Go to the **Domain Template Catalog**,
choose the domain template you like and choose **Clone Template**. This will
copy the template into your workspace.

The domain loads automatically. You will see "Legal Services" appear in
the domain list with all 20 templates available.

**Step 2: Select a template**
Choose **Engagement Letter** from the Client Communications category.
This is the recommended first template — it draws from four tables and
produces a complete, professional engagement letter in a single generation.

**Step 3: Load the Word template**
Click **Load**. Data Publisher populates the open Word document with the template with placeholders and formatting ready to go.

**Step 4: Run**
Click **Run**.

Choose the report criteria in the pop up form and in approximately 3 seconds, a complete engagement letter appears in your
Word document — addressed to Robert Thornton, from Hartwell & Associates,
signed by Margaret Hartwell, with the matter description and fee arrangement
populated from the matter record.

**Step 5: Try a second template**
Run the **Invoice** for matter **BC-INV-2024-0018** (the Delacroix
personal injury matter). Notice how the invoice automatically switches
to the contingency billing format — no configuration required. The
billing type in the matter record drives the template format.

You are now ready to connect your own firm's data. See the
**Customization** section below.

The specific record references matter. Telling the user to select "HW-2024-0047 — Thornton asset purchase" rather than "any matter" gives them a precise, repeatable experience. They know exactly what they should see. If they see something different, they know something went wrong. Specificity in Quick Start instructions is not pedantry — it is quality assurance.

The second step deliberately showcases conditional formatting without explaining how it works. The user sees the billing type switch happen automatically and thinks: how did it know to do that? That question is the beginning of genuine curiosity about the platform's capabilities. Answer it in the Advanced Usage section, not here.

Section 4: The 20 Templates

This is the longest section in the README and the most-consulted reference section for ongoing users. Every template gets its own entry with four elements: the template name, what it produces, when you would use it, and which data tables it draws from.

Do not rush this section. A template description that is too brief — "Generates a client letter" — tells the user almost nothing. A description that is too long buries the key information. Aim for three to five sentences per template: what it is, what it looks like, when to use it, and one specific detail that distinguishes it from similar templates.

## The 20 Templates

### Client Communications

**1. Engagement Letter**
A formal letter establishing the attorney-client relationship, signed by the
lead attorney, addressed to the client by name, and specifying the scope of
representation, the fee arrangement, and the client's responsibilities. Draws
from the matters, clients, attorneys, and firms tables. Use this template at
the outset of every new matter to create a professional, enforceable record
of the engagement terms.

**2. Client Status Update**
A narrative letter updating the client on recent activity, completed milestones,
and upcoming hearings or deadlines on their matter. Automatically includes a
summary of the next three scheduled hearings and the two highest-priority
deadlines. Use monthly or whenever significant matter activity warrants a
client communication.

**3. Invoice**
A detailed billing statement with three intelligent billing formats: Hourly
matters show a line-item table of all time entries with date, description,
attorney, hours, and amount; Flat Fee matters show a single professional
services line; Contingency matters show the agreed percentage with a note
that no fee is owed until recovery. Payment summary always shows total
charges, payments received, and balance due. The most technically complex
template in the domain.

**4. Payment Receipt**
A clean, simple confirmation of payment received. Shows the invoice number,
matter reference, amount paid, and balance remaining. Suitable for email
attachment or mailing. One page in all cases.

**5. Case Summary Letter**
A comprehensive three to five page summary of the matter from engagement to
present: the legal issue, the strategy employed, all proceedings and their
outcomes, current status, and recommended next steps. Draws from six tables.
Use at matter milestones, before strategy conferences, or when a new partner
is taking over a matter and needs rapid orientation.

### Legal & Compliance

**6. Retainer Agreement**
A complete retainer agreement in standard form, pre-populated with firm
letterhead, client identification, matter description, fee structure, and
payment terms. The fee section conditionally renders based on billing type —
hourly, flat fee, or contingency. Requires attorney review and client
signature before execution. Not legal advice; consult your jurisdiction's
bar requirements for required disclosures.

**7. Conflict of Interest Disclosure**
A formal disclosure document identifying the potential conflict, the basis
for the conflict, and the client's informed waiver of the conflict. Required
by most state bar rules before representation begins where any conflict
exists. Generates with matter-specific details pre-populated.

**8. File Closing Letter**
A professional letter confirming the conclusion of representation on a
specific matter, summarizing the outcome, and stating the firm's file
retention policy. Use when closing any matter, whether by settlement,
judgment, completion, or client decision.

**9. Attorney-Client Privilege Notice**
A standard confidentiality and privilege notice for attachment to emails,
correspondence, and document transmissions. Generates with firm and
attorney details. One-page format suitable for footer use.

### Court & Proceedings

**10. Hearing Preparation Sheet**
An internal attorney work product document for court appearances. Includes
the full matter context, hearing type and logistics, a structured argument
outline, the relevant deadlines for the matter, and preparation notes.
Marked as Attorney Work Product — not for client distribution. Essential
for any contested hearing or argument.

**11. Deposition Outline**
A structured outline for deposition preparation, including witness
background from the matter record, the key topics to cover, and a
framework for questions organized by subject area. The question framework
is pre-structured; the attorney adds specific questions in the document
after generation.

**12. Court Appearance Checklist**
A practical pre-hearing checklist organized by category: documents to
bring, filings to confirm, logistics to verify, client communications to
make. Cross-references the filed documents table to confirm required
filings are on record. Use the day before any court appearance.

**13. Deadline Calendar**
A prioritized deadline summary for a specific matter, organized by
criticality: Critical deadlines appear in a highlighted section at the
top, followed by High priority, followed by a complete chronological
table of all deadlines with status. Attorney notes appear where populated.
Use at weekly matter reviews and before client status calls.

### Operational

**14. Matter Status Report**
A firm-wide snapshot of all active matters: client name, matter number
and description, lead attorney, practice area, open date, and current
status. Organized by practice area. Use for weekly firm management
meetings, partner reviews, and workload assessments.

**15. Attorney Workload Summary**
A per-attorney view of active matters, total billed hours in the current
period, unbilled hours pending invoicing, and upcoming deadlines within
the next 30 days. Use for capacity planning, billing reviews, and
partner compensation discussions.

**16. Active Case List**
A concise one to two page list of all active matters with key identifiers:
matter number, client, description, practice area, and responsible
attorney. The operational quick-reference list for a busy practice.

**17. Client Contact Sheet**
A consolidated contact reference for all active clients: name, company
(if entity), phone, email, and the matters currently active for each
client. Use as the front page of a client file or as a quick-reference
for the receptionist or assistant managing incoming calls.

### Administrative & Financial / Marketing

**18. Monthly Billing Summary**
A financial overview of all invoiced matters for a period: client name,
matter, invoice number, total billed, amount paid, and balance due.
Calculates and displays firm-wide totals. Use for monthly financial
reviews, partner distributions, and accounts receivable management.

**19. Attorney Biography Sheet**
A professional one-page biography for each attorney: full name, title,
bar admission details, specialty areas, and the biographical summary
from the attorneys table. Suitable for proposals, website profiles,
speaking engagements, and bar directory submissions.

**20. New Client Welcome Package**
A comprehensive two to three page welcome document for new clients:
firm overview, the attorney assigned to their matter, communication
protocols, billing procedures, office address and hours, and a brief
matter description. Send with the executed engagement letter at
matter opening.

The template descriptions earn their length. Notice that every entry answers the implicit question: when exactly would I generate this? Operational templates name the meeting or review where they are used. Compliance templates reference the bar rule or process they support. Internal templates clarify who they are for. This specificity is what separates a reference section that users actually consult from one they skim once and never return to.

Section 5: Data Structure

This section is for the users who want to understand the data model before they start replacing sample data with real records. It does not need to be exhaustive — your docs/SCHEMA_REFERENCE.md handles the full technical detail. What it needs to do is explain the shape of the data model in plain language and show the relationships visually.

## Data Structure

The Legal Services domain is organized around a central entity: the **matter**.
Everything in the domain relates to a matter — the client it serves, the attorney
who leads it, the hearings it requires, the deadlines it carries, the billing
it generates.

### The Entity Hierarchy

firms └── clients (billed to the firm) └── attorneys (employed by the firm) └── practice_areas (offered by the firm) └── matters (assigned to a practice area) ├── hearings (scheduled for the matter) ├── deadlines (tracked for the matter) ├── billing_entries (recorded against the matter) ├── invoices (issued for the matter) └── documents_filed (filed on behalf of the matter)

### Key Relationships

**Firms → Clients, Attorneys, Practice Areas**
Every client, attorney, and practice area belongs to a specific firm. This
allows the domain to serve multiple firms from a single data load, with each
firm's documents containing only that firm's data.

**Clients + Attorneys + Practice Areas → Matters**
Every matter has a client, a lead attorney, and a practice area. These three
relationships are the core of the matter record — they determine who the
work is for, who is responsible, and how it is categorized.

**Matters → Everything Else**
Hearings, deadlines, billing entries, invoices, and filed documents all
connect to the matter. This means any document that references a matter
can automatically include all related hearings, deadlines, and billing
history through the matter's foreign key relationships.

### ClientType: Individual vs. Entity

Clients may be individuals or organizations. When `ClientType` is set to
`Individual`, templates use `FirstName` and `LastName`. When it is set to
`Entity`, templates use `CompanyName`. The engagement letter, invoice, and
case summary letter all handle this distinction automatically.

Section 6: Sample Data

A short section, but an important one. Users who are evaluating whether to purchase need to understand what the sample data covers. Users who are customizing need to understand what scenarios the sample data was designed to exercise.

## Sample Data

The domain ships with 81 records across 10 tables, representing three law firms
across New York, Chicago, and San Francisco with varied practice areas, client
types, and matter scenarios.

**What the sample data covers:**

*Billing types:* All three billing models are represented — hourly (with full
time entry records), flat fee, and contingency. The Invoice template renders
a different format for each type automatically.

*Client types:* Both individual clients (Robert Thornton, Marcus Delacroix)
and entity clients (Cascade Industries LLC, Pacific Rim Ventures Inc) are
included. Templates that address clients by name handle both formats.

*Matter status:* Both active and closed matters are included. The Active Case
List filters for active matters only; the Matter Status Report includes all.

*Payment status:* Invoices in all three states — Paid, Partial, and Unpaid —
are represented. The Invoice template calculates and formats the balance
section differently for each.

*Deadline priority:* Critical, High, and Medium priority deadlines are all
present. The Deadline Calendar renders Critical deadlines in a highlighted
section separate from the main list.

The sample data was designed to exercise every conditional branch in every
template. If a scenario exists in the sample data, the template has been
designed to handle it correctly.

Section 7: Customization

This is where the user transitions from exploring your domain with sample data to using it with their own firm's real data. The tone shifts from descriptive to instructional — concrete steps, precise file paths, specific column name references.

## Using Your Own Data

To replace the sample data with your firm's real data, replace the CSV files
in the `csv-data/` folder with your own files maintaining the same column
structure.

### The Fastest Path: Edit the Sample Files

The quickest approach is to open the sample CSV files in Excel or Google Sheets,
clear the sample records, and enter your own data. The column headers must remain
exactly as they are — column names are case-sensitive and must match the
field references in the templates exactly.

Start with these four files in this order:

1. `firms.csv` — Replace with your firm's information. If you are a single firm,
   keep only one record. Update FirmName, Address, Phone, Email, and Website.

2. `attorneys.csv` — Replace with your attorneys and staff. The BioShort field
   populates the Attorney Biography template — a two to three sentence professional
   bio for each attorney.

3. `clients.csv` — Replace with your active clients. Set ClientType to
   `Individual` or `Entity` for each record. For entity clients, leave
   FirstName and LastName blank and populate CompanyName.

4. `matters.csv` — Replace with your active matters. Set BillingType to
   `Hourly`, `Flat Fee`, or `Contingency` for each matter — this field
   controls which invoice format is used.

Add hearings, deadlines, billing entries, invoices, and documents as needed.
Templates that reference these tables will include the corresponding data
automatically.

### Column Reference

Every column name in every CSV file is documented in full in
`docs/SCHEMA_REFERENCE.md`. If you are unsure what a column is for or
what values it accepts, that document is your reference.

### What Happens If a Field Is Empty

Empty fields render as empty in generated documents — no placeholder text,
no "N/A," no error. If a template includes a section that is entirely
conditional on a field (like the retainer note in the Invoice template),
that section simply does not appear when the field is empty. You can safely
leave any field empty if the data does not apply.

Section 8: Advanced Usage

Advanced usage covers the capabilities that go beyond loading a CSV and clicking Generate. These sections serve the users who become your most loyal subscribers — the ones who have integrated the domain deeply into their workflow and want to push its limits.

## Advanced Usage

### Connecting Live Data Sources

Rather than maintaining CSV files manually, DataPublisher supports
connections to external data sources with one-click refresh to sync
the latest data.

**Google Sheets (OAuth2):** Maintain your client and matter data in a shared Google
Sheet. Click **Connect Google Sheets** in the Data Sources panel, sign in to your
Google account, and grant DataPublisher read-only access. Once authorized, select
your spreadsheet and map each sheet to a domain table. DataPublisher imports a snapshot
of your data. When you update the sheet, click the **Refresh** button (🔄) on the data
file card to sync the latest data — no CSV exports needed. Tokens refresh automatically.
See `docs/DATA_SOURCES_INTEGRATION.md` for step-by-step OAuth setup instructions.

**Microsoft Excel Online (OAuth2):** If your firm uses Excel Online (OneDrive or
SharePoint) for matter tracking, click **Connect Microsoft Excel**, authorize with
your Microsoft 365 account, and select your workbook. Map worksheets (e.g., "Clients",
"Matters") to domain tables. DataPublisher imports the data into its local database
for fast document generation. When you update the Excel file, click **Refresh** on the
data file card to sync the changes. DataPublisher handles token refresh automatically —
after initial authorization, the connection works indefinitely until you disconnect.

**SQL Server / Practice Management Systems:** For firms using practice
management software with SQL Server backends (Clio, MyCase, Practice Panther),
the SQL connector allows direct database queries with username/password or
Windows authentication. Enter connection details once, map database tables to
domain tables, and click **Refresh** to import the latest data. DataPublisher
stores a local snapshot for fast, reliable document generation.
Recommended: Create a read-only SQL user with SELECT permissions only for security.

### Forking and Customizing the Domain

The generator script (`scripts/generate-legal-services-templates.js`)
is included in the domain package and is the source of truth for all
20 templates. To customize any template — add a field, change a layout,
add a new section — edit the corresponding function in the generator
script and run it to regenerate that template.

To add a 21st template, add a new function to the script, add its entry
to the templates array, update the domain-config.json to include the new
document type, and regenerate.

The domain is yours. Fork it, extend it, specialize it for your practice
area, and publish your enhanced version to the marketplace. Other firms
benefit from your improvements; you earn revenue from your specialization.

### White-Label Customization

To brand the domain for a specific firm rather than a generic legal practice,
update the `makeDocument()` function in the generator script to include
the firm's actual logo and letterhead colors. The `headerFirmName` parameter
can be replaced with a static firm name rather than a placeholder, locking
the letterhead to a specific firm's identity.

Section 9: Troubleshooting

The troubleshooting section is the section you write for 11pm. That is the time when users are trying to get something done for tomorrow morning and something is not working. Every question in this section should be one that a real user actually asked, or one that you can confidently predict they will ask.

## Troubleshooting

**The domain does not appear after loading**
Confirm that you selected `domain-config.json` specifically, not the
`legal-services/` folder itself. Confirm that the `csv-data/` folder is
present inside the domain folder and contains all 10 CSV files.

**A template generates but some placeholders show as literal text**
The field name in the template does not exactly match the column name in
the CSV. Column names are case-sensitive. `ClientID` and `clientid` are
different. Open the relevant CSV file and verify the exact column name
spelling.

**The Invoice shows the wrong billing format**
Confirm that the `BillingType` field in `matters.csv` contains exactly
`Hourly`, `Flat Fee`, or `Contingency` — including the exact capitalization
and spacing shown here. Any variation will cause the conditional to fail
silently and render the default (blank) billing section.

**Client name shows as blank on the Engagement Letter**
Check the `ClientType` field for the client record. If it is set to
`Entity`, the template uses `CompanyName` rather than `FirstName`/`LastName`.
If `CompanyName` is also blank, the name field will be empty. Populate
the field appropriate to the client type.

**The Invoice does not show billing entry line items**
Billing entries only appear when `InvoiceID` in `billing_entries.csv`
matches the `InvoiceID` of the invoice being generated. Confirm that
the billing entries you want to include have their `InvoiceID` field
populated with the correct invoice ID.

**Dates appear in YYYY-MM-DD format rather than a readable format**
Data Publisher renders dates exactly as they appear in the CSV. To display
dates in a readable format (e.g., September 15, 2025), either format them
in the CSV before importing, or use the `{{FormatDate}}` function in the
template. See the placeholder syntax reference in
`docs/SCHEMA_REFERENCE.md` for date formatting options.

**The domain loads but shows 0 records for some tables**
Confirm that the CSV file for the affected table is present in `csv-data/`
and that the filename exactly matches the table name defined in
`domain-config.json`. Filenames are case-sensitive on Linux and macOS.

**Generated documents do not reflect changes I made to the CSV**
Data Publisher caches CSV data for performance. After editing a CSV file,
click **Reload Data** in the Templates panel to force a fresh read from disk.

**A template generates an error instead of a document**
Check that all tables listed in the template's `relatedTables` in
`domain-config.json` are present and have at least one record. A template
that references a table with no records may fail to generate on some
configurations.

**I need a template that is not in the 20**
The generator script is included. Add your template function, add its
entry to the templates array, update `domain-config.json`, and regenerate.
The domain is designed to be extended. See the Advanced Usage section above.

The Closing Section: Making It Personal

After the nine functional sections, the best READMEs end with something that reconnects the technical document to the human purpose it serves. This is not required — it is the difference between a good README and a great one.

---

## A Note on What You Are Actually Building

The documents this domain generates are not abstractions. They are the
engagement letters that establish trust between an attorney and a client
at the beginning of a difficult situation. They are the invoices that allow
a small firm to maintain the cash flow that keeps good attorneys practicing.
They are the hearing preparation sheets that help an attorney walk into a
courtroom ready rather than overwhelmed. They are the deadline calendars
that prevent the kind of missed filing that ends careers.

The Legal Services Domain automates the production of these documents.
But what it actually does is give attorneys and their staff more time —
time they can spend on the work that requires a human being: listening,
advising, advocating, and delivering the judgment that no template can replace.

That is worth building well.

---

*Legal Services Domain for Data Publisher for Word — Version 1.0.0*
*Built on the Data Publisher platform. $10/month gives you access to this
domain and every other domain in the marketplace.*
*Questions or feedback? [Your contact information here]*

The README Quality Checklist

Before you publish, read your README against this checklist. Every "no" is a revision.

The Hook Does it open with the user's problem, not a product description? Could someone who has never heard of Data Publisher understand what this domain does from the first paragraph? Does it name a specific target user?

Quick Start Can a new user complete all five steps without leaving the README? Does each step have a specific action with a specific expected result? Are the example record references specific enough that the user knows exactly what they should see?

Template Descriptions Does every template description answer "when exactly would I use this"? Are the most complex templates' capabilities described specifically enough that a user understands what makes them valuable? Are all 20 templates documented?

Data Structure Is the entity hierarchy shown visually or structurally, not just listed? Are the key foreign key relationships explained in plain language? Is the ClientType (or equivalent individual/entity distinction in your domain) called out explicitly?

Troubleshooting Does it address the case-sensitivity of column names? Does it address the most likely conditional rendering failures? Does it address the data caching issue? Does it tell users what to do when none of these answers solve their problem?

Tone Is it written for the user, not for the developer? Does it avoid jargon except where jargon is the precise term? Is every section as long as it needs to be and no longer?

How Long Should the README Be?

The right length is the length that answers every question a serious user will ask without including content they have to skip. For most domains, that is 1,200 to 1,800 words — approximately the length of the README you have seen constructed in this chapter.

The SchoolCoop README runs to over 400 lines in its source form. The legal services README, following the structure above, would be approximately the same. That is the benchmark: comprehensive enough to be a genuine reference, tight enough that every section earns its place.

One practical test: print the README and read it as if you have never seen the domain before. If you can follow the Quick Start and generate your first document without opening any other documentation, it is long enough. If any section makes you think "why does this exist?", it is too long.

Chapter Summary

The README does three jobs: marketplace listing, user guide, and reference manual. It has nine sections in a precise order designed to serve three different reader types — evaluators, new users, and experienced users — each of whom needs different information at different points in their relationship with your domain.

The Hook opens with the user's problem, not a product description. The Quick Start gets a new user to their first generated document in five steps. The Template Catalog answers "when exactly would I use this" for every one of the 20 templates. The Troubleshooting section is written for 11pm.

The README is the only document in your domain package that speaks directly to a human being. Write it accordingly.

What's Next

Chapter 7 covers testing and validation — the systematic process of confirming that every template, every relationship, and every data scenario in your domain works correctly end to end. You have built it. Now you prove it.

Volume 5 — Building Intelligent Systems: Building Organizational Knowledge Systems on Data Publisher for Word Part of the Building Intelligent Systems Series