About This Documentation
This page explains how the 44Net wiki is proposed to work and how contributors can think about adding or improving documentation.
It aims to describe the assumptions behind the structure you see here.
Other documentation systems approach organization with folders and hierarchies. With MediaWiki, the hierarchy is flat, and structure emerges through navigation, linking, categories, and templates. This wiki embraces that approach, organizing around a small number of essential concepts and leaving it to the editors to link pages together in a way that makes sense for each topic.
Purpose of the Wiki
The 44Net wiki exists to help people:
- Understand what 44Net is and why it exists
- Find ways to participate
- Build projects and services
- Collaborate in stewarding the community
The ultimate goal is to promote participation by promoting understanding. Along the way, we want to help the reader feel more competent and more confident about building with 44Net.
Pages in this wiki apply two dimensions of structure:
| Dimension | Question |
|---|---|
| Conceptual Element | What part of the 44Net world is this about? |
| Page Archetype | What is this page trying to do for the reader? |
Conceptual Element + Page Archetype = A Page.
Here are more details about each of these dimensions.
The Conceptual Elements
With MediaWiki’s facilities for categorization and navigation, we don’t need a strict taxonomy from the outset. Still, there are a few general conceptual categories that are important to the sustainability of the 44Net program and that should be reflected in the documentation.
| Conceptual Element | Core Question | Typical Content |
|---|---|---|
| About 44Net | What is 44Net? | Explanations, history, core ideas |
| Provisioning | How does 44Net become available? | Methods, onboarding, setup guides |
| Use Cases | What do people do with 44Net? | Project examples, inspiration, applications |
| Applications | What tools support 44Net? | Portal docs, dashboards, software usage |
| Community | How is 44Net stewarded? | Governance, policy, collaboration |
- About 44Net
- Orientation and explanation of what 44Net is, in and of itself. This includes history, context, and the core concepts that define 44Net as a thing. This is probably a mix of philosophical, observational, and slightly technical material.
- Provisioning
- How participants actually put 44Net subnets or IP addresses on their devices or networks. This would include general explainers as well as practical, step‑by‑step instructions.
- Use Cases
- “Use cases,” meaning things people do with 44Net. The point is to help people envision what they too could do with 44Net by showing them what others have done. This is probably a mix of inspirational and practical material.
- Applications
- Conceptual and practical documentation related to tools that make 44Net work. This includes the Portal, the 44Net Connect dashboard, `ampr-ripd`, etc. This is ”open this, click that” type documentation for tools that are unique to 44Net.
- Community
- Governance, policy, collaboration, and stewardship. How 44Net is managed, how decisions are made, and how volunteers can get involved. This includes rules of the road and “how to be a good citizen,” but also info about the mailing lists and how to get involved in the community.
Documents that fall outside these categories are not necessarily out of scope. The point is, we want to be sure to cover at least these kinds of things.
Moreover, the structure should emerge from the content, not the other way around.
- Note: The term “Provisioning” is used intentionally. Participants are not connecting to a single centralized network, so language about “connecting” can be misleading. People don’t exactly dial up to something, rather they provision 44Net resources onto systems and networks they operate. This more accurately reflects 44Net’s distributed nature. It also helps avoid confusion with the thing named “44Net Connect,” which is one way to provision 44Net but not the only way.
If there is an overarching organizing principle, it might be this: Organize around aspects of people’s experiences. What do they want to do? What are they working with? How can we help? This helps keep it more user‑centric than technology‑centric. We want to serve the people who are trying to use 44Net, rather than just describing technology for its own sake.
Page Archetypes
The wiki generally adopts a handful of recognizable types of pages. Being deliberate about the type of page you are writing can help focus the material, and following recognizable patterns gives the reader helpful clues that reduce cognitive load, making the material easier to understand.
| Page Archetype | Reader Intent | Primary Goal |
|---|---|---|
| Concept Page | Understand | Build shared mental models |
| How-To Guide | Do | Enable successful action |
| Reference Page | Look up | Provide authoritative detail |
| Orientation / Landing Page | Decide | Guide navigation and discovery |
| Project Page | Explore | Show real-world examples |
| Stewardship Page | Participate responsibly | Explain governance and expectations |
Concept Page
Explains what something is and why it exists. Demystifies something. These pages provide overviews and introduce ideas. They are not step‑by‑step instructions, but they might include examples and links to related procedures.
Reader intent: Help me understand this.
Examples
Characteristics
- Narrative explanation
- Framing and context
- Relationships to other concepts
- Links to related how-to guides and reference material
Concept pages are interpretive more than instructional.
How‑To Guide
Help someone accomplish a specific task with a clear successful outcome. This is where step-by-step instructions with annotated screenshots go.
Reader intent: I want to do this thing.
Examples
Characteristics
- One goal per guide
- Clear, sequential steps
- Observable indicators of success
If a reader cannot successfully complete the task by following the steps on the page, the guide is unfinished, regardless of how well it is written.
Reference Page
Provide authoritative “look it up” type information.
Reader intent: I need some details.
Examples
- API documentation
- Technical specifications
- Policy requirements
Characteristics
- Precise
- Structured
- Non-linear
Reference pages are meant to be consulted as needed.
Orientation or Landing Page
Help readers understand a topic and decide where to go next.
Examples:
These pages are like trailhead signposts. They should be welcoming and informative to help readers find what they need. Links to how-tos and references pages live here.
Project Pages
Describe something a participant has built.
Reader intent: What is this thing I saw someone doing with 44Net?
Purpose:
- Showcase real deployments
- Help demonstrate what’s possible
- Inspire others to join a project or start one of their own
- Link outward to active work, code repositories, documentation, Discord, etc.
Like QRZ, but for 44Net projects.
Stewardship Pages
Describe how the community is supported and maintained.
Examples:
At heart, stewardship pages are about what community members expect of one another and how the community works together.
Editorial Discipline
Two types of pages are especially important to 44Net’s mission and deserve special care: Concept Pages and How‑To Guides.
Concept Pages Must Be Clear
A reader should leave able to answer:
- What is this?
- Why does it exist?
- Why would I use it?
- How does it fit into the bigger picture?
Concept pages are more like Wikipedia articles than user manuals. They should help readers form mental models, provide context, and give background or framing to practical instructions found elsewhere.
How‑To Guides Must Work
A guide succeeds only if a reader can complete the task.
Every How‑To should include:
- A statement of the goal
- Prerequisites
- Sequential steps, with screenshots and other resources as needed
- A verification step allowing the reader to confirm they have succeeded
- Links back to the related concept page
- Links to related articles that answer “Great, so what’s next?”
Deciding Where a Page Goes
Although the wiki is generally flat, “folder structure” can help maintainers by keeping related pages together. For example, all documentation related to the Portal application lives under the “Portal/” prefix.
- Note: This is not for navigation purposes or for the reader’s benefit. The reader will use links and categories to find their way around. Any folder structure is for the maintainers’ benefit, to help them find and manage related pages.
Also, this is not a hard rule, just a helpful convention.
When unsure where a page belongs, try the ownership rule:
Place the page under the concept that would feel incomplete if the page disappeared.
Examples:
- Portal DNS management → Portal/DNS
- If the documentation on the Portal’s DNS functions disappeared, people would not know how to manage their DNS records. The Portal documentation would therefore be incomplete without it, so it belongs under the Portal/.
- DNS delegation in general → DNS/Delegation
- If the documentation on DNS delegation disappeared, people would would struggle to understand DNS delegation. The DNS documentation would therefore be incomplete without it, so it belongs under DNS/.
When starting a new page or group of pages, ask yourself: am I documenting a new concept that deserves its own top-level page, or am I creating concept/how-to/reference documentation for an existing concept? If the former, create a new top-level page. If the latter, place it under the existing concept.
Categories Over Hierarchy
So MediaWiki does not actually track pages in folders. What is its native way to organize pages? Categories and links.
Categories provide the multidimensional organization that paths alone cannot. A page can belong to multiple categories, and categories can be nested. This allows for more flexible organization and navigation than a strict hierarchy.
Contributors should add categories rather than restructuring page paths.
Contributors should also use categories liberally. If a page belongs to a category, it should be in that category. If it belongs to multiple categories, it should be in all of them.
Readers rarely browse the wiki as a directory tree.
They experience it through:
- the Main Page
- topic landing pages
- contextual links
- search results
The goal is discoverability: perfect hierarchy is less important than reliable navigation. Pages may move over time, but clarity for readers must be maintained.
An Invitation
The 44Net wiki is part of the commons it describes.
Its structure will continue to evolve as participants build, document, and teach one another. Contributors are encouraged to improve explanations, refine navigation, and leave the next reader slightly less confused than they were when they arrived.
Good documentation here will pretty much always be ongoing, unfinished work in progress.