IT & TechnologyArchive edition6 min read

Designing a small internal knowledge system

Help people find and maintain procedural information without duplicating effort.

Connected infrastructure nodes and concentric paths — Designing a small internal knowledge system
Original ARTware computational illustration.

The answer to a routine technical question might already exist somewhere in a team's accumulated material. It could be in the notes accompanying an old project, in the conversation where a change was announced or in a temporary document prepared for a previous handover. People who were present when the information was created know roughly where to look; newer colleagues repeat the investigation or ask someone to recover the missing context. A useful internal knowledge system reduces that dependence on personal memory. It does not require the team to document everything it knows. It requires a way to identify information that will be used again, organize it around recognizable work and maintain it as the systems it describes change.

Find the questions that recur

Start by collecting ordinary questions the team needs to answer. How does a maintainer generate the public website from its source? Which output needs to be reviewed before publishing it? What should happen when a scheduled data transfer misses a run? Where does a new colleague find the supported development requirements for a particular project? These questions suggest useful handbook pages because each corresponds to an activity with a recognizable result. Ask people to describe their last attempt to locate such information. The difficulty might come from not knowing the right search phrase, finding several conflicting copies or locating a document that describes an earlier version of the system. The solution depends on which difficulty is occurring.

Review existing material selectively rather than moving every note into a new location. A short investigation of a problem that was resolved a year ago may remain useful as historical context, but it is different from the current instructions for performing a release. An old conversation can explain why a decision was made, while a current procedure should tell the reader how to act now. Identify documents that are still used, extract the enduring parts of useful temporary notes and mark older information appropriately. It may be better to preserve a decision record separately from the concise procedure it informed. Combining everything into a single document can make its present status unnecessarily difficult to understand.

Write pages around tasks and decisions

Organize maintained instructions according to work that people recognize. A handbook could contain a page about normal publishing, another about returning to an earlier version and a third about preparing a development environment. Each page should have a title that helps the reader recognize its purpose, even when the title is viewed outside its section in a search result. A heading called General Notes provides almost no useful distinction when several teams use it. A heading identifying the restoration of an approved site version is far more descriptive. Use the vocabulary people already use to refer to the systems and tasks, and include an important synonym where the existing terminology varies.

Related reading: Internal linking for a technical knowledge library.

A practical instruction begins by stating when it applies and what it is expected to produce. If the procedure requires legitimate access, a particular environment or a previously prepared artifact, describe the prerequisite before the step that depends on it. Explain each important verification in terms of the expected outcome. For site publication, include checking an agreed page, a navigation relationship and a referenced asset, not merely confirming that a hosting operation reported success. Place the fallback procedure nearby through a descriptive reference. Keep account information and sensitive configuration in their appropriate management systems; a handbook may explain how an authorized person obtains them but should not reproduce private access details in ordinary text.

Give material a clear status and owner

Maintained knowledge needs someone to notice when its accuracy changes. Record the role responsible for reviewing each important page, whether that is a maintainer of a particular application, a publishing operator or a team responsible for shared infrastructure. The role can remain stable when staff change. A review date is useful when it represents an actual check of the contents, not merely a date that is updated automatically while old instructions remain unchanged. Define a simple status for a document whose procedure no longer applies. A reader searching for a discontinued method should be able to recognize the old document's status and, where appropriate, discover the supported replacement without following an obsolete instruction accidentally.

Layered flowing curves with fine network-like intersections
ARTware visual study. A complementary computational composition.

Use more detailed lifecycle information only where it provides a real benefit. A short-lived investigation might need nothing more than a date and an explanation of its outcome. A production procedure may justify recording the application version or environment in which it was checked. Material awaiting confirmation can be kept as a draft rather than presented as authoritative. When an important change is released, ask whether any corresponding instruction or decision record needs to be amended. Updating relevant documentation during the work is usually easier than attempting to recall all the changed details during a separate cleanup months later. Someone reviewing a technical change can help identify instructions it invalidates.

Keep the editing path easier than the informal alternative

An excessively elaborate documentation process can push contributions back into chat conversations and isolated notes. Short corrections should not require a contributor to learn a specialized publishing system simply to fix a misleading instruction. Decide how people can propose a change, how it is reviewed when necessary and when it becomes visible to the readers concerned. A small team can often use the same controlled change process that it already understands for its other project material. If non-developers contribute operational content, provide an editing path they can use comfortably. Make formatting and organization predictable so contributors can concentrate on explaining the activity instead of choosing a different presentation for each page.

A modest navigation structure works well when the material is still small. Group pages under the tasks they support and add related links where they clarify prerequisites, alternative procedures or shared concepts. Avoid making copies of a long shared instruction for each project unless its behavior is genuinely different. A shared page can describe the ordinary method, while a project-specific page records its special requirement and refers to the common material. Search can complement navigation, but it cannot compensate entirely for inconsistent titles and several apparently current copies of the same instruction. Review a few terms that colleagues actually use when asking questions and see whether the relevant pages can be found.

Check whether the system works without the author present

Give a colleague a representative task and ask them to locate the current instructions without telling them the expected title. Observe whether they recognize the relevant page, can tell when it was checked and discover an appropriate fallback reference. For a new project setup, ask them to complete a small task using the material and note where they have to request additional information. This reveals more than asking whether the handbook looks well organized. A reader may find an attractive page but still be unable to distinguish an example value from a required setting. Record those points of uncertainty and make specific improvements. Repeat the exercise with a person who already maintains the system, since experienced maintainers and new colleagues may need different kinds of context.

Judge the knowledge system by how easily it supports recurring work. Useful material should become simpler to find than recreating an answer from an old discussion. A maintained instruction should describe the current process, and a historical decision should retain enough context to explain why it matters. When an area has little activity, there is no obligation to fill it with extensive generic documentation. Begin with procedures people need, establish a reliable way to update them and add structure as the collection grows. A small collection of trusted and discoverable pages gives a team a stronger shared foundation than a large archive whose readers must first decide which parts are still worth believing.

Explore the implementation area: IT consulting.