It is essential to structure knowledge in order to share it efficiently. Well documented code is just one aspect. Tasks, plans, reports, and project presentations are also much known. But there's much more, ranging from early sketches to specifications, deployment tips, knowledge route maps, training materials, test samples, operational procedures, project's organization, meeting notes, formal models, development techniques, and so forth.

How can you organize all that knowledge cleanly, notably using a wiki... so that it would not just be useful to developers and frustrate managers hardly finding the information they seek, or vice-versa ? How so many people with so different information requirements can all be satisfied at the same time?

Wiki's with rich hyperlinked pages definitely help providing multiple navigation paths into the same information. A good bunch of tags and keywords significantly accelerate searches. Yet a wiki is basically organized as a hierarchical set of pages whose structure is also often used to navigate.

What kind of structure would be most efficient?

Save time organizing and structuring all kinds of information about a project.

Start with a structure that will be sustainable and can cleanly host new information categories as the project progresses. Stop wondering where the hell this team (or a colleague) has stored the kind of information you look for. Provide a clean - repeatable - project knowledge structure that can become a common template for all kinds of projects.

Foster considerable time savings when you search info about a project, either when you join it, either when the project is rich and complex and drives "cognitive overloads" forcing you to permanently refresh your knowledge to be productive.

Follow the "Organum" structure illustrated further down as source of inspiration for adding pages to your project's wiki. The structure is borrowed from the methodology Praxeme whose Enterprise System Topology is supported by means to organize all the information about a project from design to delivery. A simplified Organum is proposed here that is sufficient for 90% of IT projects.

Get Started:

(follow the illustrated mind map)

At the root, your project's home page would typically provide a short project summary, a who's who contact list, summarize milestones and progress, a picturesque sketch or architecture diagram, and provide quick links (recent activities, FAQ, route maps for different profiles, abbreviations, ...)

Below, we can organise knowledge in four categories:

1. a "Repository" of all external source materials: client specs / initial statement / contract, links to 3rd party products or libraries used in the project, docs, test data samples, standards, regulations, methods, tips, market data, technologies, patterns, etc.
2. a "Products" section hosting all project's productions from the vision/strategy to (links to) code, including, sketches, models, API design notes and links to API specs, coding practices, naming rules, available tools, etc.
3. an "Operations" section holding all the bits of knowledge necessary to configure, build, test, deploy, and operate the application(s). Here we document the staging environments and provide manuals / tutorials for administrators, developers, testers, operators, and end users.
4. an "Organisation" describing who does what (project organisation and management), why (decisions, meeting notes, quality plan, risks and mitigation), when (updated plans, time line) and resources / budget. This section will also archive all the project's presentations to the team or stakeholders / clients.

In other words, these four categories respectively hold:

1. all the knowledge you shall bring along before starting; mostly as commented pointers, be it internal (e.g. the Enterprise Continuum of TOGAF) or external / generic;
2. the "what" (current): up-to-date descriptions, specifications, statements;
3. the "how" (current): up-to-date procedures and processes;
4. the "who" "why" and "when" (with timeline/history), with all collaboration (meeting notes) and communication activities (presentations).

Clearly, there will be many hyperlinks between contents in different sections and to external platforms / information sources.

Reminder:

• The first purpose of a knowledge repository is to save time: finding the right information in minimum time.
• Avoid pure hierachical project pages in a wiki; i.e. 'empty' pages that only hold a path to (or group) child pages and contain no information but at most a listing of sub-pages. There is always something to tell about any level of information and surely helpful guidance and links to provide.
• Never forget to tag wiki pages with keywords, and provide a cloud of tags elsewhere
• Never forget that your wiki bears a complete history of all pages & attachment updates, built-in! so do not lose time maintaining inventories of versions/changes but for true chronological stuff like meeting notes, major releases (past and ahead) or key decisions.
• Hyperlink your content. The page hierarchy is only your storage structure. Navigation is most efficient via hyperlinks that help navigate in all directions, not only top-down.
• A link to the information is as useful as the information itself; henceforth avoid copying and duplicating but link it.
• The Organum is not about a project wiki alone, but about everything that concerns a software project. Part of this global information is better hosted by specialized servers for source control and source code documentation (e.g. GitHub / GitLab), project management (e.g. JIRA), bug tracking, modelling (e.g. Modelio, Enterprise Architect, Mega), and of course API Management (e.g. Swagger, Postman, and many vendors). Do not duplicate this information but link it abundantly. The project's wiki will become the entry point to everything about a project.