About This Documentation - Revision history

KI5QKX: mw push

2026-03-05T04:42:12Z

mw push

← Older revision		Revision as of 04:42, 5 March 2026
Line 15:		Line 15:

	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.		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.

KI5QKX: mw push

2026-03-01T01:14:36Z

mw push

← Older revision		Revision as of 01:14, 1 March 2026
Line 152:		Line 152:
	Examples:		Examples:
	* [[Main Page]]		* [[Main Page]]
	* [[~~Ways to Connect~~]]		* [[Provisioning Methods]]
	* [[What People Build]]		* [[What People Build]]

KI5QKX: mw push

2026-03-01T00:14:45Z

mw push

← Older revision		Revision as of 00:14, 1 March 2026
Line 260:		Line 260:

	Good documentation here will pretty much always be ongoing, unfinished work in progress.		Good documentation here will pretty much always be ongoing, unfinished work in progress.
			[[Category:Documentation]]

KI5QKX: mw push

2026-02-28T23:20:31Z

mw push

← Older revision		Revision as of 23:20, 28 February 2026
Line 32:		Line 32:
	Here are more details about each of these dimensions.		Here are more details about each of these dimensions.

	== The ~~Conceptual Elements~~ ==		== 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.		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.
Line 75:		Line 75:
	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.		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~~ ==		== 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.		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.
Line 95:		Line 95:
	\|}		\|}

	=== Concept ~~Page~~ ===		=== 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.		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.

Line 114:		Line 114:
	Concept pages are interpretive more than instructional.		Concept pages are interpretive more than instructional.

	=== ~~How‑To Guide~~ ===		=== 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.		Help someone accomplish a specific task with a clear successful outcome. This is where step-by-step instructions with annotated screenshots go.

Line 130:		Line 130:
	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.		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~~ ===		=== Reference page ===
	Provide authoritative “look it up” type information.		Provide authoritative “look it up” type information.

Line 147:		Line 147:
	Reference pages are meant to be consulted as needed.		Reference pages are meant to be consulted as needed.

	=== Orientation or ~~Landing Page~~ ===		=== Orientation or landing page ===
	Help readers understand a topic and decide where to go next.		Help readers understand a topic and decide where to go next.

Line 157:		Line 157:
	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.		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~~ ===		=== Project pages ===
	Describe something a participant has built.		Describe something a participant has built.

Line 170:		Line 170:
	Like [https://qrz.com QRZ], but for 44Net projects.		Like [https://qrz.com QRZ], but for 44Net projects.

	=== Stewardship ~~Pages~~ ===		=== Stewardship pages ===
	Describe how the community is supported and maintained.		Describe how the community is supported and maintained.

Line 182:		Line 182:


	== Editorial ~~Discipline~~ ==		== Editorial discipline ==

	Two types of pages are especially important to 44Net’s mission and deserve special care: Concept Pages and How‑To Guides.		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~~ ===		=== Concept pages must be clear ===
	A reader should leave able to answer:		A reader should leave able to answer:
	* What is this?		* What is this?
Line 195:		Line 195:
	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.		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~~ ===		=== How‑to guides must work ===
	A guide succeeds only if a reader can complete the task.		A guide succeeds only if a reader can complete the task.

Line 206:		Line 206:
	* Links to related articles that answer “Great, so what’s next?”		* Links to related articles that answer “Great, so what’s next?”

	== Deciding ~~Where~~ a ~~Page Goes~~ ==		== 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.		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.
Line 227:		Line 227:
	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.		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~~ ==		== Categories over hierarchy ==

	So MediaWiki does not actually track pages in folders. What is its native way to organize pages? Categories and links.		So MediaWiki does not actually track pages in folders. What is its native way to organize pages? Categories and links.
Line 239:		Line 239:


	== Navigation ~~Philosophy~~ ==		== Navigation philosophy ==

	Readers rarely browse the wiki as a directory tree.		Readers rarely browse the wiki as a directory tree.
Line 253:		Line 253:


	== An ~~Invitation~~ ==		== An invitation ==

	The 44Net wiki is part of the commons it describes.		The 44Net wiki is part of the commons it describes.

KI5QKX: mw push

2026-02-26T20:00:21Z

mw push

← Older revision		Revision as of 20:00, 26 February 2026
Line 16:		Line 16:
	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.		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:		Pages in this wiki apply two dimensions of structure:
Line 77:		Line 77:
	== Page Archetypes ==		== 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 it easier to understand ~~the material~~.		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.

	{\| class="wikitable"		{\| class="wikitable"
Line 114:		Line 114:
	Concept pages are interpretive more than instructional.		Concept pages are interpretive more than instructional.

	=== How‑To ~~Guides~~ ===		=== 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.		Help someone accomplish a specific task with a clear successful outcome. This is where step-by-step instructions with annotated screenshots go.

Line 130:		Line 130:
	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.		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 ~~Pages~~ ===		=== Reference Page ===
	Provide authoritative “look it up” type information.		Provide authoritative “look it up” type information.

Line 147:		Line 147:
	Reference pages are meant to be consulted as needed.		Reference pages are meant to be consulted as needed.

	=== Orientation ~~and~~ Landing ~~Pages~~ ===		=== Orientation or Landing Page ===
	Help readers understand a topic and decide where to go next.		Help readers understand a topic and decide where to go next.

Line 180:		Line 180:
	At heart, stewardship pages are about what community members expect of one another and how the community works together.		At heart, stewardship pages are about what community members expect of one another and how the community works together.

	~~----~~

	== Editorial Discipline ==		== Editorial Discipline ==
Line 210:		Line 210:
	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.		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.

	~~'''NB:'''~~ 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.		{{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.		Also, this is not a hard rule, just a helpful convention.
Line 237:		Line 237:
	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.		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.

	~~----~~

	== Navigation Philosophy ==		== Navigation Philosophy ==
Line 251:		Line 251:
	The goal is discoverability: perfect hierarchy is less important than reliable navigation. Pages may move over time, but clarity for readers must be maintained.		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 ==		== An Invitation ==
Line 259:		Line 259:
	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.		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 ~~is not finished work — and never~~ will be.		Good documentation here will pretty much always be ongoing, unfinished work in progress.

KI5QKX: mw push

2026-02-26T19:46:48Z

mw push

← Older revision		Revision as of 19:46, 26 February 2026
Line 1:		Line 1:
	~~== About This Documentation ==~~

	This page explains how the 44Net wiki is proposed to work and how contributors can think about adding or improving documentation.		This page explains how the 44Net wiki is proposed to work and how contributors can think about adding or improving documentation.

KI5QKX: mw push

2026-02-26T19:29:55Z

mw push

New page

== 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:

{| class="wikitable"
! 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.

{| class="wikitable"
! 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 it easier to understand the material.

{| class="wikitable"
! 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 ====
* [[44Net Connect]]
* [[IPIP Mesh]]
* [[BGP|BGP on 44Net]]
* [[DNS|DNS within 44Net]]

==== 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 Guides ===
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 ====
* [[44Net Connect/Quick Start|44Net Connect Quick Start]]
* [[Portal/Sign Up|Create a Portal account and verify your callsign]]

==== 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 Pages ===
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 and Landing Pages ===
Help readers understand a topic and decide where to go next.

Examples:
* [[Main Page]]
* [[Ways to Connect]]
* [[What People Build]]

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 [https://qrz.com QRZ], but for 44Net projects.

=== Stewardship Pages ===
Describe how the community is supported and maintained.

Examples:
* [[Policies]]
* [[Volunteer|Volunteer Roles]]
* [[Verification|How Verification Works]]

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.

'''NB:''' 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.

----

== Navigation Philosophy ==

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 is not finished work — and never will be.