Core Ideas
NUU Citations uses six ideas in a chain. The chain runs from a citation in a document down to the work itself. The registry stores only the Description. The other five ideas tell you what a Description is, and what it is not.
The six ideas
Citation. A pointer from a document to a source. It is the act of citing.
Bibliography Entry. The formatted line that a reader sees. It is how a citation looks on the page.
Description. The stable record of what the source is. It names the work and holds its provenance. This is the centre of the product.
Instance. A particular copy or location of the work. It is how you reach the work.
Version. A particular edition or printing of the work. It is which form of the work you mean.
Document. The work itself as a body of content.
Today only the Description layer is live in the app. The other five ideas still matter. They stop you from mixing a record of a source with the file, the edition, or the citation.
The Description
A Description is one record in the registry. It has a permanent identity. It has one owner. The owner is the NUU account that created it.
A Description holds:
- a title
- an optional disambiguator
- authors, organisations, and platforms
- an optional date of publication
- an optional format, such as paper, book, video, or lecture
- an optional version marker
- an optional identifier such as a DOI
- how the work is stored and reached
- an optional location for that copy
- a short summary and a longer summary
- optional notes
- optional tags that only you see
Authors, organisations, and platforms are names. Each name can carry a link.
A Description also has visibility, optional shares, and optional private fields. Read About Visibility.
How the nouns relate
You describe a source once. The Description is that record. Other people cite the Description. They do not copy the authors and title into each tool.
The Description can point at an instance. The instance says how you reach the work. The work may live at a link. The work may live only in a private vault. The work may be pasted into the record. The work may be a link that no longer opens.
The version marker on a Description names the edition. It is not the Version primitive in the chain. Read About Versions.
The disambiguator tells two of your Descriptions apart when they share a title. It is not an edition marker. Read Tell Apart Two Sources with the Same Title.
The same Description can live in the registry and as a Markdown file. The file is another form of the same record. Read About the Markdown Form.
Identity
Each Description gets a permanent identity when you create it. That identity does not change when you edit the title or the summary. Other people and other NUU tools reuse that identity. They do not create a second record for the same source.
You own the Descriptions you create. You can edit them. You can remove them. Removal also removes the shares on that Description. You cannot undo removal.