Knowledge & operationsBLoc Guide Builder11 min read

Building Editable User Guides, Dependency Maps, and Localization Style Guides from Project Evidence

Draft user guides, dependency maps, and localization style guides from local project evidence — no AI API, no code execution, export to Word or Markdown.

Executive summary · 11 min read
  • Scan evidence locally: up to 240 files and 5 MB of text, with no AI API, no project code execution, and no project modification.
  • Missing-information warnings and the read-file inventory tell you exactly what the draft does not know.
  • Draft user guides, dependency maps, and style guides from the same evidence so documentation stays consistent.
  • Export session edits to Word or Markdown before closing, and verify generated instructions against the real tool.
Portable Drafts & Dependency Map Filters: When continuing work across sessions, save a portable .wgdraft.json file—it preserves text, approved embedded image bytes, and review state that plain Markdown exports omit. When exporting a standalone HTML dependency map, use the Observed filter for declared Python/package imports and the Inferred filter for pattern-matched JavaScript references.

Documentation fails quietly. The user guide was accurate for the 1.0 release, the onboarding checklist lives in someone's head, and the localization style guide is a set of verbal habits rather than a document. When a new engineer or a new language vendor arrives, the gap between the written process and the actual one costs days. BLoc Guide Builder approaches the problem as an evidence task: it reads a project folder locally, inventories what it found, and drafts editable documentation from that evidence — without an AI API, without running project code, and without modifying the project.

Why project documentation drifts

Documentation drifts because writing it competes with shipping, and because the people who could write it no longer remember what is non-obvious.

  • Knowledge is implicit. The build command, the deployment quirk, the reason a setting exists — documented nowhere, known by two people.
  • Docs are written once. Nothing regenerates them from the project as it is now, so they describe a past version with confidence.
  • Style guidance is tribal. Terminology choices live in reviewers' heads, and each new vendor rediscovers them by correction.
  • Onboarding pays the bill. Every gap is paid in senior time answering questions the documentation should have covered.

An evidence-first workflow attacks the root cause: generate a draft from what the project actually contains, then edit with intent.

The cost of drift shows up in a familiar scene: a release ships, a support engineer asks where the new setting is documented, and the answer is a chat message that itself becomes stale within a month. Documentation written from evidence can be refreshed the same way — run the scan again, compare the warnings, and update only the sections the evidence changed.

How evidence scanning works, and its limits

You choose a project folder, and the scanner reads supported documentation, manifests, and source files — up to 240 files and 5 MB of text per scan. It collects command-line help, web routes, package scripts, public docstrings, and HTML button labels as documentation evidence. The scan is strictly local: no AI API is called for drafting, project code is never executed, and the selected project is not modified.

The limits are deliberate guardrails. The scanner skips common dependency and build folders, hidden or likely secret files, large files, and symlinks — which keeps credentials and vendored code out of the evidence pool. Because a scan reads rather than tests, it cannot tell you whether a documented command actually works; verify generated instructions against the running tool before publishing them.

Reading without running

Local-only processing is a security property, not a slogan. Because no project code is executed and no AI API receives your files, scanning a private repository leaks nothing: the evidence stays on the machine where the scan ran. The trade-off is honesty about what a read can know — the scanner can report that a route exists and what its docstring claims, but only execution can prove the route behaves as documented. Treat every drafted instruction as a hypothesis your review either confirms or corrects.

Evidence sourceWhat it typically documents
README and documentation filesPurpose, setup steps, usage notes
Package manifestsDependencies, versions, declared scripts
Command-line help outputCommands, flags, and defaults as the tool reports them
Web routesThe API or site surface a newcomer must know
Package scriptsBuild, test, and release tasks
Public docstringsFunction and class intent in the authors' words
HTML button labelsReal UI terminology for style guides

Missing-information warnings and the file inventory

Two review artifacts make the scan auditable. Missing-information warnings surface the places where evidence was absent — no license file, no test command found, a route with no description — so the draft states gaps instead of papering over them. The read-file inventory lists every file the scan read. Use the inventory to confirm the scanner saw the right tree: a scan that read only three files did not fail, it told you the folder was nearly empty, and that is a finding too.

Drafting user guides and business documentation

User guide drafts follow the shape of the evidence: setup from manifests and help output, tasks from routes and scripts, interface reference from real labels. Business documentation drafts describe what the project does in operational terms for stakeholders who will never read the code. Both are starting points with structure and traceability to what was read; your edits add the judgment that no scan can supply, in the built-in browser editor.

Building dependency maps from manifests

Dependency map drafts collect what the manifests and related evidence declare about the project's building blocks, together with warnings where evidence was missing. They are useful for vendor onboarding, security review preparation, and any moment someone asks "what does this actually depend on?" Keep the warnings visible when you share the map: a dependency map without its gaps invites false confidence.

Localization style guides from real terminology

Style guide drafts are grounded in the product's actual strings: HTML button labels and public docstrings show the terminology users already see. The draft collects terminology, rules, and open questions — where usage is inconsistent, the draft says so instead of silently choosing a winner. Review each section, resolve the open questions, and export either the style guide or the AI instruction variant for translation workflows. This pairs naturally with template-based translation guided by terminology and writing rules; see the related guide below.

Typical open questions look like this: the interface says "Sign in" on one screen and "Log in" on another; documentation says "workspace" while button labels say "project"; error messages mix sentence case with title case. Each is a decision only the product owner can make, and a style guide that lists them explicitly is doing its job — the alternative is every vendor deciding differently.

Editing and exporting drafts

Edit the Markdown draft in the browser, then export your changes to Word or Markdown. Session edits live in the session: export before closing, because unsaved edits are not recoverable afterwards. Export to Word when reviewers work in tracked changes; export to Markdown when the documentation lives in a repository next to the code it describes.

Version the exports alongside the project and note which scan produced them. A guide exported from last quarter's evidence is not wrong so much as unaudited — knowing its evidence date tells the next maintainer exactly how much scrutiny it deserves.

Production note: export session edits to Word or Markdown before closing the app. The draft you see is session state, and closing without exporting is the one mistake this tool cannot undo for you.

Operational checklist

  1. Pick the folder that represents the current state of the project, not an archived copy.
  2. Run the scan and read the missing-information warnings before looking at the draft.
  3. Check the read-file inventory against the tree you expected the scan to cover.
  4. Draft the document type you actually need — user guide, business documentation, dependency map, or style guide.
  5. Edit in the browser editor, resolving open questions rather than carrying them into the export.
  6. Verify every generated instruction against the real tool; the scan reads, it does not test.
  7. Export to Word or Markdown before closing the session.
  8. Store the export with the project and note the scan date so future refreshes stay comparable.

Technical FAQ

Does Guide Builder send my code to an AI service?

No. Drafting runs locally without an AI API. The tool reads supported files, drafts from them, and never executes project code. Internet is required only for customer activation and periodic license verification.

What happens if my project exceeds the 240-file or 5 MB limits?

The scan reads up to 240 files and 5 MB of text, skipping dependency and build folders, hidden or likely secret files, large files, and symlinks. Point the scan at the subfolder that matters most — documentation and manifests first — and run a second scan on another folder if needed.

Can I use the output as a translation memory?

No. The style guide export documents terminology, rules, and open questions for human review, including an AI instruction variant. Translation itself happens in your CAT tool or translation workflow, guided by the style guide you approve.

Why does the draft include warnings instead of filling gaps?

Because invented content is worse than an explicit gap. A draft that says a test command was not found tells the reviewer exactly where to contribute; a plausible guess would quietly become policy.

The BLoc Guide Builder tool page covers setup and options, and the interactive walkthrough shows a scan-to-export session; use the request form to confirm supported file structures for your project. For adjacent workflows, read exporting and auditing Confluence spaces locally and batch AI document translation with terminology workflows.

BLoc Guide Builder · Documentation

Ready to apply this workflow in production?

Turn local project evidence into editable guides, business documentation, dependency maps and localization style guides. Pricing: $7 / month or $70 / year.

← All 14 localization engineering guides