Technical learning docs

Technical Learning Docs

Use this skill when the user asks for a knowledge-building document, introduction, tutorial, primer, concept explainer, or study guide for a technical topic (AI/ML, data systems, infrastructure, developer tools, protocols, databases, etc.). It is especially relevant when the topic contains abstract terms and the user is using the document to prepare for real work.

Core principle

Do not only produce an expert reference. For unfamiliar or abstract domains, produce a learning path:

1. Concept primer first or alongside the deep guide — explain the vocabulary in plain language.
2. Then the detailed technical guide — architecture, APIs, workflows, practices, pitfalls.
3. Then implementation/usage examples — code, commands, schemas, checklists.

If the user says the first document is “晦涩”, “抽象”, “看不懂”, or calls out terms like “向量 / embedding / index / schema / chunk”, immediately switch to a plain-language primer instead of adding more expert jargon.

User-facing style for Tian Chao

• Write in Chinese unless the user asks otherwise.
• Prefer 飞书文档 delivery for durable documents when tools are available.
• Avoid Markdown tables in chat replies; tables inside Feishu docs are acceptable when they improve scanning.
• Be concise in the chat: provide the document link and what was covered, not a long duplicate of the document.
• For concept education, use analogies before formal definitions.
• Translate English technical terms on first use: Embedding（嵌入向量/语义向量）, Blob（二进制大对象）, FTS（全文检索）.

Recommended document structure

A. Concept primer

Use for abstract/first-contact topics.

1. “先用一句话说清楚”：what problem the system solves.
2. Everyday analogy: map/coordinates, warehouse, index card, library catalog, GPS, etc.
3. Core vocabulary glossary with “不是 / 它是”.
4. One complete lifecycle diagram.
5. Small code snippet with line-by-line translation.
6. Common confusions and pitfalls.
7. Learning order and “how to explain it in a meeting”.

B. Deep technical guide

Use after or alongside the primer.

1. Positioning and architecture.
2. Core capabilities.
3. Data model / schema design.
4. API usage and minimal runnable examples.
5. Indexing/search/training workflow.
6. Production practices and pitfalls.
7. Checklist.
8. Official references.

Workflow

1. Identify the reader’s current level from the prompt.
   • “继续补充知识” → likely needs both overview and practical usage.
   • “好多名词看不懂 / 好抽象” → primer mode.
2. Gather authoritative references if the topic has fast-moving APIs or versions.
3. Draft the content as a Feishu-friendly document:
   • Start with a callout that states the goal.
   • Use headings, lists, callouts, diagrams, and glossary tables.
   • Put code in small snippets and explain variables.
4. Verify the document artifact:
   • Validate XML/Markdown if writing a Lark doc.
   • Create/update the Feishu document.
   • Fetch outline or a small section to confirm successful creation.
   • If diagrams/whiteboards were requested, inspect create/update warnings and fetch the document to confirm the expected diagrams actually exist; if Mermaid parsing failed, insert a self-contained SVG whiteboard after the relevant heading.
   • When using lark-cli docs +create --title, do not also include a <title> tag in the content; choose one title source to avoid duplicate-title warnings.
5. In the final chat response, give the link and a short summary.

Reference patterns

• references/research-doc-with-diagrams-pattern.md — workflow for detailed Chinese research docs with Feishu whiteboard diagrams, including verification and fallback from Mermaid to SVG.

Pitfalls

• Do not assume the user already understands the vocabulary in a detailed guide. If many domain nouns appear, add a primer or glossary proactively.
• Do not respond to frustration with more process explanation. Deliver the missing artifact quickly and explain blockers only briefly.
• Do not make examples only toy-level. Include a small toy example for intuition, then connect it to the real workflow.
• Do not mix model concepts, database concepts, and storage concepts without a lifecycle diagram; users need to see where each piece sits.

References

• references/lance-multimodal-primer-pattern.md — session-derived pattern for explaining Lance/LanceDB, vectors, embeddings, multimodal search, and related vocabulary to a learner.