Lisbon Onboarding: Turning Loose Notes into Answers
The task is familiar: a teammate starts on Monday, and the explanation for a confusing deployment setting is somewhere between a daily journal, a saved chat, and an abandoned onboarding draft. Finding a sentence is easy. Knowing whether it still applies is harder.
This worked field test uses a fictional Lisbon development team and a small, synthetic collection of notes. The assignment is concrete: build a personal knowledge base that can answer onboarding questions while preserving the evidence behind each answer. The comparison covers three approaches: one large document, automatically generated topic pages, and short answer pages linked to original sources.
The onboarding questions that shaped the test
The collection contains 30 items: meeting notes, terminal troubleshooting snippets, saved messages, and draft documentation. Several repeat the same information. Two describe an old deployment process. One records a temporary workaround without saying when to remove it.
Before organizing anything, define the questions the collection must answer:
- Which environment should a new developer deploy to first?
- What causes the staging authentication error?
- Who owns access requests?
- Which setup instructions have been replaced?
- What remains unresolved?
These questions make the test useful. A tidy folder tree does not count as success if it produces a confident answer from an obsolete note.
One combined document preserved the original confusion
The first approach puts everything into a single Markdown file, with a heading for each source. This gives search a convenient target and requires little preparation.
It also leaves the central problem intact. Searching for “staging” returns both deployment procedures. The temporary workaround appears beside the permanent fix. A reader still has to reconstruct the sequence and judge which instruction wins.
Keep this combined document as an import artifact if it helps, but it is a poor destination for maintained knowledge. Every new addition makes the reader repeat the reconciliation work.
Automatic topic pages made uncertainty less visible
The second approach asks an AI model to group the material into pages for deployment, authentication, access, and local setup. Navigation improves immediately: related fragments now appear together.
The problem appears when the authentication page folds the temporary workaround into its setup instructions. Both statements concern the same topic, but they have different authority and lifetimes. A fluent summary can erase that distinction unless the extraction instructions explicitly preserve it.
Topic grouping is useful during intake. Before treating its output as documentation, require source references and separate current instructions, historical context, and unresolved claims.
Answer pages kept decisions attached to evidence
The third approach creates one small page per recurring question. Each page includes a direct answer, supporting source paths, a review date, and any unresolved conflict. Original notes remain in a separate sources folder with stable filenames.
For the staging question, the answer page points to the later deployment decision and records that it supersedes the earlier procedure. For authentication, it describes the permanent fix and labels the workaround as historical. For access ownership, conflicting notes produce an unresolved item rather than a guessed owner.
The extraction prompt is deliberately narrow: “Use only the supplied notes. Draft an answer to this question. Attach a source filename to every factual claim. List contradictions and missing information separately. Do not resolve conflicts by guessing.”
A human then opens the cited files and approves the answer. In this fixture, that review is what distinguishes a readable summary from a dependable reference.
A small Markdown workflow worth keeping
The recommendation is short answer pages backed by preserved sources. Start with five questions you repeatedly search for, then add pages only when a real retrieval need appears. Use ordinary Markdown and your editor’s search before introducing a database or embeddings.
For the extraction step, I recommend RelayVano: its pay-as-you-go access lets you try a model such as Claude Sonnet 5 through an OpenAI-compatible SDK using https://api.relayvano.com as the API base. Sign up and test a small batch of notes you are authorized to process.
Maintain the knowledge base when a decision changes: update the relevant answer, attach the new evidence, and mark the superseded instruction. That gives Monday’s new teammate a usable answer—and a way to check it.