Documentation topic
How this documentation is made and how to contribute: topics, paragraphs, editing, ordering, examples and related paragraphs.
How this documentation is made
This documentation is itself a set of nanopublications. It is a resource maintained by the Nanopublication space; each chapter is a topic, and each block of text within a chapter is a paragraph. Every topic and every paragraph is a nanopublication of its own, signed by whoever wrote it, and the pages you are reading are assembled from them by a query.
That makes the documentation a wiki: any member of the space can add a chapter, add a paragraph, revise or remove one, and the history of every change is preserved.
Who can contribute
Members of the Nanopublication space — at member tier or above — can add and edit. What they publish appears on the pages; what anyone else publishes about the same topics is stored on the network but not shown here.
To become a contributor, ask an admin of the space for a role. You can also declare yourself an observer of the space in the meantime, which is a way of saying you are interested; it does not by itself let your edits show.
Adding a chapter
A chapter is about a thing, and it is identified by that thing's own URI: the chapter on templates is about the class of nanopublication templates, the chapter on spaces about the class of spaces. To add a chapter, use "add topic…" above the list of chapters, which opens the "Declaring a documentation topic" form: give the URI, a title, and this documentation as the collection it belongs to. A position, such as 210, places the chapter in the list, and a one-sentence description is shown there under its title.
A chapter about something without a URI of its own — a tool, a way of working — gets one under this documentation's namespace, https://w3id.org/spaces/nanopub/r/docs/, and names what it covers with the form's "is about" field.
The form has another field, "the described resource", in its publication-info section; enter the chapter's URI there too. It is what makes the chapter get a page of its own — without it the chapter is listed but cannot be opened.
Adding a paragraph
On a chapter's page, "add paragraph…" opens a form asking for a title, the text, and a position. The text can be plain, or simple HTML for emphasis, code and links. Keep a paragraph to one point; a chapter reads best as a series of short, titled blocks rather than a few long ones.
The paragraph is published under your name and appears on the page as soon as the network has picked it up, usually within a minute.
A paragraph's own page
Every paragraph has a page of its own: click its heading, or choose "open" from its menu. The page shows the paragraph's current text with its "edit…" and "remove…" entries, the examples linked to it, the paragraphs related to it, and its version history — every version anyone published, newest first, with the current one marked.
Three things are done from there. "Add example…" links anything with a URI — a nanopublication, a page, a service address — as an example of what the paragraph describes, with a short note on what to look at. "Add related paragraph…" links it to a paragraph a reader should also see, possibly in another chapter; the link shows on both pages. And "restore this version…" in the history makes an earlier version current again, whoever published it.
Editing a paragraph
Every paragraph has an "edit…" entry in its menu, whether you wrote it or someone else did. It opens the form with the current text; publishing makes a new version that keeps the paragraph's identity, and the page shows the newest version by any member. The earlier version is kept, listed in the paragraph's version history, and can be restored from there.
So a correction to someone else's text is made the same way as to your own. Nothing needs the original author's key, and nothing is lost.
Ordering
Paragraphs are ordered by their position, a short text such as 030 compared letter by letter. Positions in tens leave room: a paragraph to go between 030 and 040 gets 035. Paragraphs without a position come first, in title order, so give every paragraph one.
A paragraph can be moved by editing its position, and a whole chapter renumbered the same way, one edit per paragraph.
Removing
Every paragraph has a "remove…" entry in its menu, open to any member, whoever wrote the paragraph. It publishes a new version that marks the paragraph as removed, with an optional reason. The paragraph then disappears from its chapter and from the chapter's paragraph count, and its own page shows a notice in place of the text.
A removal is undone like any other change: the version history lists it, and "restore this version…" on an earlier row brings the text back. A whole chapter is removed the same way from the list of chapters, and restored by adding it again with the same URI. Retracting is still open to whoever published a version, but it withdraws only that version, and the one before it, if any, becomes current again.
Writing well here
Say what a thing is for before saying how it works. Use the vocabulary terms a reader will have to type, and explain the rest in words. Prefer one concrete example to a list of options. Where a fact depends on a version of a tool, say so, since these pages outlive releases. And when you are unsure whether something is still true, check it before writing it down — a wrong sentence here is read by everyone who comes after you.
This page is a copy of the topic Documentation topic of the Nanopublication Docs. Each paragraph is a nanopublication. In Nanodash you also find their examples, related paragraphs, and version history, and members of the nanopub space can edit them there.