Writing guidelines

What belongs on the network, and the bar every guide has to clear.

Academy Network is the definitive library of how to do things, and definitive is the whole job: one authoritative guide per topic, good enough that nobody needs to write another. Before a guide reaches the official index, a jury of volunteers who know the subject reviews it against the standard on this page. Read it before you write, and your guide will usually pass the first time.

What belongs here

A guide belongs on Academy Network if it teaches a reader to do something real:

• Practical skills: welding a joint, suturing a wound, soldering a board, laying brick, sharpening a chisel.
• Building things: from a transistor to a logic gate to a processor; from a wall to a house; from a carburetor to an engine.
• Understanding real systems: how a cell works, how an electrical grid balances load, how a compiler turns text into a program, taught so the reader can reason about and work on them, not just recite facts.
• New methods: a better way to do something that already has a guide, submitted as a method inside that guide.

General reference belongs on Wikipedia; opinion belongs on a blog. If a page can't answer "what will the reader be able to do after reading this?", it isn't a guide.

Structure rules

These rules are what make the network different from a search engine, and reviewers enforce them strictly:

• One definitive guide per topic. If a guide on your topic already exists, improve it or challenge it with something better; don't duplicate it. Alternative techniques go in the guide's methods section, each as its own sub-guide.
• Guides live at a level. Level 1 assumes the reader knows nothing about the subject. A guide at any higher level may only assume what lower-level guides in its subject already teach.
• Declare prerequisites. Every guide lists the guides a reader should complete first, and every prerequisite must sit at a lower level than the guide itself. No circular ladders, no gaps.
• Self-contained entries. A guide teaches its whole topic. "See this YouTube channel for the rest" doesn't survive review; external resources may supplement, never substitute.
• Translations link, never fork. A guide in another language is registered as a translation of the original so improvements can flow both ways.
• Build the web. Link the first mention of every concept that has a guide. If the guide doesn't exist yet, link it anyway: it shows as a red link and joins the wanted-guides list, which is how the network tells its writers what to build next. A guide with no links in or out is a shed, not a room in the library.

Media and sources

The network is built to outlive the web around it, and guides have to be written the same way:

• Attach media, never link to it. Don't link to a YouTube video: download the video and attach it to the guide. If the original is taken down tomorrow, your guide still teaches. The same goes for images, PDFs, diagrams, and datasheets: attach the file itself instead of linking to where it lives today.
• Attached is also faster here. Attachments are served by the network itself, from peers who already hold them nearby. An external link has to leave the network and crawl the open web through Tor, which is slow and can fail. On this network the attached copy loads faster than the linked one.
• Cite everything you used. List the sources your guide draws on (books, papers, sites, videos) in a sources section at the end. Ordinary web links are fine there, because they document where the knowledge came from. It's the guide's content that must never depend on an external link staying alive.

Ads and donations

There are no ads on guides. There are no ads anywhere. The protocol has no ad mechanism and no tracking, so there is nothing to sell and no one to sell it to. That's permanent, not a launch promise.

What a guide can have is a single Donate button at the very bottom:

• It belongs to the duke. Whoever originally wrote the guide chooses the link it points to (Patreon, Ko-fi, your own page, wherever you take donations), or deletes the button entirely. Other people editing the guide's content can never touch it; it isn't part of the content at all.
• One button, at the bottom, clearly labeled. No banners, no inline plugs, no "support me" paragraphs in the middle of the steps. The button is the whole surface.
• It's an external link, and the app says so. The donate button is the only thing on a guide that leaves the network, so the app warns before opening it in your browser.
• Abuse gets it struck. Property changes don't go through review, so the editors police them instead: a donate link pointing at a store, an affiliate scheme, or somebody other than the duke gets struck, and repeated abuse costs the dukedom.

Quality standards

• Complete and testable steps. A competent reader at the guide's level can follow the steps and end up with the result. Steps state what success looks like ("the solder joint should be shiny and cone-shaped"), so readers know when something went wrong.
• Accurate. Claims of fact are correct and, where they're not common knowledge at that level, supported: by citation, by demonstration within the guide, or by the verifiable experience of doing it.
• Plain writing. Define every term the reader's level doesn't already cover. Short sentences beat impressive ones. Jargon without definition is a defect, not a style.
• Honest about danger and difficulty. If a step can hurt someone or destroy the workpiece, the guide says so before the step, not after. Safety warnings are part of teaching, not decoration.
• Media that teaches. Images and diagrams appear where words fail, every image has alt text describing what it shows, and file sizes stay reasonable; readers on slow connections matter.

Why guides get sent back

A rejected submission is not a verdict: it returns to you with every juror's written reasoning, and most guides pass on the second attempt. The common reasons:

Jurors must explain every vote in writing; a bare "no" is invalid and costs the juror their verifier status. The feedback loop is the system working, not the system rejecting you. How review works, step by step, is covered in Contributing.

Removing guides

Review keeps bad guides out. Removal votes take published guides down. If a guide shouldn't be on the network at all (not "needs editing" but "shouldn't exist"), any user in good standing can open a removal petition with a written reason, and the whole community votes.

• Voting stays open for 30 days. Anyone can vote remove or keep, one vote per person.
• Votes are weighted by earned standing: credit you build by writing and reviewing guides. A brand-new account carries no weight, so nobody can mob a guide off the index, or shield one from removal, by spinning up throwaway identities.
• Passing needs a real quorum of standing and a 75% supermajority. Then the guide is delisted from the official index and every copy of the app deletes it from the storage it donates to the network.
• Anything less and the guide stays. Quality complaints belong in an improvement submission, not a removal petition.

The petition, the votes, and the reasons stay on the network permanently as the public record of why the guide was removed. The bar is deliberately high because removal exists for guides that are dangerous, deceptive, or plainly out of scope, not for guides someone dislikes. The same petition tool also governs the network's people and rules: see Governance.