Table of contents :

Chunking Installation and User Guides

100-days-of-chunking-with-llamaparse-and-undefined-038

Table of contents :

Installation and user guides are among the highest-value documents in a WooCommerce support and operations knowledge base. They contain exact procedures, version-specific instructions, warnings, configuration values, and troubleshooting steps. They are also easy to damage during parsing because meaning often depends on hierarchy, numbered steps, tables, screenshots, and code blocks.

A useful chunking pipeline should preserve the relationship between a task, its prerequisites, its ordered steps, and the expected result. Splitting every paragraph into an independent vector record may produce technically valid chunks that are operationally useless. The goal is to create chunks that can answer questions such as “How do I configure the webhook for the payment gateway?” without losing the settings, sequence, or warnings required to complete the task.

Why installation guides need structure-aware chunking

A typical guide may contain several layers of meaning:

  • A product, extension, or integration name
  • Supported WooCommerce and WordPress versions
  • Prerequisites such as API credentials, PHP extensions, or administrator permissions
  • An ordered installation procedure
  • Configuration values and example commands
  • Verification instructions
  • Troubleshooting and rollback procedures

These elements should not all be treated as interchangeable text. A prerequisite belongs to the task that follows it, while a troubleshooting section may need to be retrieved separately. Heading hierarchy is therefore a useful first approximation of document structure, but it should be combined with semantic rules for lists, tables, warnings, and code.

Parse the source before choosing chunk boundaries

Use LlamaParse to convert PDFs and other document formats into structured text before applying application-specific chunking rules. The parser output should retain headings, paragraphs, lists, tables, and code-like content where possible. Do not begin by splitting the raw file at a fixed character count. That approach can separate a command from its explanation, detach a warning from the step it qualifies, or place a table heading in a different chunk from its values.

For each parsed document, capture identifying metadata before chunking:

  • document_id: a stable identifier for the source file or guide
  • document_title: the guide title
  • product: the WooCommerce extension, integration, or service
  • version: the documented plugin, API, or platform version
  • locale: the language and regional variant
  • source_url: the canonical documentation address
  • updated_at: the source revision date when available

These fields should be copied to every resulting chunk. A support assistant can then filter or rank results by extension and version instead of returning an obsolete installation method that happens to contain similar wording.

Use procedure-aware chunk boundaries

For an installation or configuration guide, a good default is to create a parent chunk for the task and child chunks for substantial steps. The parent should contain the relevant title path and a short summary. Each child should include enough context to stand alone in a search result.

For example, a source structure such as Payment Gateway > Installation > Configure webhooks can produce chunks with metadata like:

{
  "document_id": "gateway-guide-2025-02",
  "product": "Example Gateway for WooCommerce",
  "version": "4.2",
  "heading_path": ["Payment Gateway", "Installation", "Configure webhooks"],
  "section_type": "procedure",
  "step_start": 1,
  "step_end": 3
}

The text for each step should normally include the step number, action, related field names, and any immediate warning. If a procedure has twelve short steps, combining two or three adjacent steps may be better than creating twelve very small records. Conversely, a long step containing several independent settings may need to be split at subheadings or task boundaries.

Keep prerequisites with the procedure

Prerequisites should be attached to the procedure parent or repeated in each child chunk when they materially affect execution. A chunk that says “Paste the signing secret into the Webhook secret field” is incomplete if the secret must first be generated in a separate dashboard. Include the dependency in the chunk or store an explicit relationship to the prerequisite chunk.

Keep ordered steps ordered

Preserve list numbering in the text. Numbering helps retrieval and tells a downstream system that the items form a sequence rather than a collection of unrelated facts. Avoid joining steps from different procedures merely because they fit within a token budget.

Keep warnings attached to the affected action

Warnings about test mode, data loss, cache clearing, or credential exposure should remain in the same chunk as the action they qualify. A warning stored by itself may be retrieved without the action, while an action stored without its warning can lead to an unsafe answer.

Handle code, commands, and configuration values separately

Installation guides commonly include WP-CLI commands, PHP snippets, JSON payloads, environment variables, and URL patterns. Preserve these as code blocks rather than normal prose. A code block should remain intact unless it exceeds the retrieval size limit; if it must be split, split at a complete statement or logical object.

For example, this command and its explanation should remain together:

wp plugin activate example-gateway
wp wc payment_gateway update example_gateway --user=admin

Do not normalize values that are case-sensitive, whitespace-sensitive, or environment-specific. Store the surrounding explanation as text, but preserve the exact code representation for display and downstream use. It is also useful to classify code blocks with metadata such as code_language, command_type, or environment.

Chunk tables by task, not by row count

Tables often contain the exact values needed to configure a WooCommerce integration. A table describing field names, accepted values, and defaults should usually be converted into a self-contained chunk that includes its caption, heading path, and column names.

For large compatibility matrices, split by product or platform version while repeating the table headers in every chunk. For field-reference tables, split by functional group such as credentials, checkout behavior, order status mapping, and webhooks. Never create a row-only chunk that omits the column headings; values such as “Enabled” or “30” are ambiguous without them.

Recommended chunk metadata for agency knowledge bases

Metadata is especially important when an agency manages several stores, plugins, and client-specific integrations. In addition to document identity, consider storing:

  • content_type: installation, configuration, upgrade, troubleshooting, or reference
  • section_type: prerequisite, procedure, warning, code, table, verification, or rollback
  • product_slug and plugin_version
  • platform_scope: WordPress, WooCommerce, hosting, payment provider, or external service
  • audience: developer, merchant, support agent, or administrator
  • task_id and parent_chunk_id
  • source_page or page range for PDF traceability
  • content_hash for detecting revisions and removing stale embeddings

Use metadata filters before semantic search where possible. A question about configuring a payment gateway for WooCommerce 9 should not be answered from a guide written for a different major version merely because both documents mention webhooks.

Design chunk sizes around answerability

There is no universal token count for procedural documentation. A practical starting point is to target approximately 250 to 700 tokens for ordinary procedure chunks, with overlap only where a sentence or prerequisite would otherwise be lost. Larger chunks may be appropriate for a complete short procedure, while smaller chunks are useful for isolated field definitions or error resolutions.

Evaluate chunks using representative support questions rather than size alone. For each chunk, ask:

  1. Can a support agent identify which product and version it applies to?
  2. Can the agent perform the described action without reconstructing missing context?
  3. Are prerequisites, warnings, and expected results available?
  4. Can the chunk be cited back to the exact source location?
  5. Would retrieving an adjacent chunk improve the answer?

If the answer to the last question is frequently yes, preserve a parent-child relationship or retrieve neighboring chunks by task_id and sequence number. This is generally more reliable than increasing overlap across the entire document.

Example pipeline with LlamaParse and Undefined

A production workflow can separate parsing, normalization, chunking, indexing, and retrieval:

  1. Submit the source guide to LlamaParse and retain the parsed block types and source locations.
  2. Normalize headings, list markers, table headers, and code blocks without changing configuration values.
  3. Classify sections as prerequisites, procedures, warnings, references, verification steps, or troubleshooting.
  4. Build chunks using heading paths and procedure boundaries.
  5. Attach document, product, version, and task metadata to every chunk.
  6. Pass the resulting records to Undefined for indexing and retrieval according to the project’s configured schema.
  7. Run retrieval tests using real agency support questions and inspect whether the returned chunks preserve complete procedures.

The exact Undefined configuration depends on the deployment and schema, but the interface between the parser and the indexing layer should be explicit. A useful record contains the cleaned text, stable identifiers, ordered position, metadata, and a source reference. Keeping this contract stable makes it possible to reparse documents or change embedding models without rewriting the source-processing logic.

Test installation-guide chunks with realistic WooCommerce questions

Build an evaluation set from questions that support teams actually receive, including:

  • “Where do I find the API keys for the staging store?”
  • “Which webhook events are required for refunds?”
  • “Why is the payment method missing from checkout after activation?”
  • “What should I disable before migrating from the legacy API?”
  • “Which PHP version does this extension release support?”

For every question, record the expected source section, required metadata filters, and whether the answer needs one chunk or a sequence of chunks. Check for common failures such as a returned code block without its prerequisites, a version mismatch, a missing table header, or a troubleshooting answer that omits the verification step.

Manage revisions and stale procedures

Installation guides change when WordPress, WooCommerce, payment APIs, or extension settings change. Generate a content hash for the normalized source and use the document version or revision date in the record. When a guide changes, replace or deactivate all chunks associated with the old revision rather than updating only the changed paragraph.

For client-specific runbooks, keep the vendor guide and the agency’s validated procedure as separate sources. Link them through metadata or a related-document identifier. This preserves the vendor’s original instructions while allowing the agency to document environment-specific values, deployment sequencing, and rollback checks without silently modifying the upstream guide.

Trending posts
You might also like