Requirements and plans

Knowledge: your team's pages

Spaces of pages that keep every version, private spaces, review before publishing, templates, comments and files.

Knowledge is Yavaren's own wiki: spaces of pages written in Markdown. Every save is kept, so you can see who changed what, compare two versions and bring an old one back. It is a module: an admin of your organisation switches it on (PUT /v1/modules/knowledge); until then nothing of it is shown.

Today Knowledge is used through the Yavaren API (/v1/knowledge/..., listed under API); the console's Knowledge screens are not available yet. The names of actions below are the API's routes in plain words.

Spaces

For the admins of your organisation.

An admin creates a space with a short key (for example ENG) and a name. A space can be restricted: only the people on its list see it, each as a reader (reads), an editor (writes) or an owner (also manages the space and approves its pages). Admins always see every space.

Someone who is not on a restricted space's list does not see it at all: not in the list of spaces, not in search, not in links. A viewer of the organisation reads pages but never changes them.

Pages

• New page: start empty or from a template: business requirements, product requirements (PRD), technical specification, architecture decision record (ADR), API documentation, runbook, security document, user guide, release notes. A page holds up to 500 KB of text.
• Save: if someone saved the page after you opened it, Yavaren does not overwrite their work: reload, then save again.
• History: every version, a comparison of any two, and Restore, which saves the old text as a new version.
• Links: write [[REQ-7]], [[PAY-12]] or [[Page title]] to point at a requirement, a work item or another page. A link to something you may not see shows as restricted, without its title.
• Files: attach PDF, Word (.docx), Markdown, text, PNG or JPEG files. They are always downloaded, never opened in the browser.
• Comments: members comment; the author, or an owner of the space, can change or remove a comment.
• Archive: the page's owner, an owner of the space or an admin archives a page. Every version is kept.

Review before publishing

A space can ask for an owner's approval before a page is published. Then:

1. Save the page as a draft and choose Submit for review.
2. An owner of the space (or an admin) reads it and chooses Approve, which publishes exactly that version, or Ask for changes.
3. If the page changes after you submitted it, submit it again: an approval always covers the text that was read.

Only a person signed in approves. A key, a runner or Yavaren itself never approves a page.