Wiki Protocols ​

This is the set of rules to follow while working on the wiki. If you're in a hurry, the overview is a must-read; you can skip the rest for the most part.

Overview ​

The Daedalus wiki is where everybody can write about the things that normally needs to get shared between the development team members of Daedalus. This is an internal wiki; only us dev members can add content to it.

What belongs here:

• Library information
• Step-by-step protocols on commonly-used methods
• Descriptive information for projects and their parts
• Public plans and strategies
• Official documentation on Daedalus products and services

What does not belong here:

• Private information that must not be shared in public
• Unofficial information about Daedalus
• Private plans that must not be made public yet
• Guides, blogs, and discussions that don't get used within the normal workflow
• Educational information

Basically, the wiki is a reference for the things we do. It has to be made in such a way that members can view a wiki post when they either forget to do something or are showing a newly-onboarded member what to do.

Wiki Collaboration Workflow ​

sequenceDiagram
	writer ->> issue: creates a new issue
	writer ->> issue: links draft via PR
	writer ->> issue: assigns reviewer
	issue ->> reviewer: begins peer review
	reviewer ->> issue: submits review
	issue ->> writer: receives review
	writer ->> writer: revises draft
	writer ->> issue: links revised draft via PR
	issue ->> reviewer: second review
	reviewer ->> issue: approves changes
	reviewer ->> issue: calls maintainer
	maintainer ->> issue: merges PR

sequenceDiagram
	writer ->> issue: creates a new issue
	writer ->> issue: links draft via PR
	writer ->> issue: assigns reviewer
	issue ->> reviewer: begins peer review
	reviewer ->> issue: submits review
	issue ->> writer: receives review
	writer ->> writer: revises draft
	writer ->> issue: links revised draft via PR
	issue ->> reviewer: second review
	reviewer ->> issue: approves changes
	reviewer ->> issue: calls maintainer
	maintainer ->> issue: merges PR

Figure 1. Sequence diagram for issue-dependent roles.

Anyone can write for the wiki. But to make sure that everyone writes correct and complete information every time, we have a decentralized issue-dependent role system in place for peer reviews.

Issue-dependent Roles ​

Issue-dependent roles are roles that only matter within the issue. In the case of our wiki, we have three of these roles:

• Writer
• Reviewer
• Maintainer

The writer (or writers for multiple authors) is the person creating the draft and writing the new wiki page article. Writers are also responsible for selecting the review panel for their article.

Reviewers act as a peer review team that not only ensures correctness but also manages linking and referencing to other wiki articles. Whenever possible, there should be two members on the review team: one expert who knows the topic well enough and someone who would do most of the linking and referencing for the article.

Lastly, maintainers are people with maintainer/owner rights over the wiki. They should be able to merge Pull Requests.

Maintainers can be either reviewers or writers, but reviewers can not be writers on the same article they are writing and vice versa.

Making New Articles ​

1. To make a new article, create a new issue on the Daedalus Wiki repository.
2. Title the issue as [new] <Article Title / Topic Name>.
3. On the "Comment" area, add information about the piece you want to write. Note: You can start writing before or as soon as you've made an issue. The issue is mostly for communication purposes between writers, editors, and other related members.
4. An editor can pitch in and provide more details about the topic. All discussions related to creating a new article should be within that issue.
5. To submit a draft, create a Pull Request with your article as a Markdown file. Images, if there are any, should be placed within the public/assets/yourArticleTitle folder.
6. If submitting with a draft, include the link to your draft. For example: localhost:5000/suggestions/title-here if in the suggestions folder or localhost:5000/docs/title-here if in the docs folder.
7. Once approved, an editor will then add your article into the directory of wiki articles and update the internal links of articles related to it.

Initiating Edits ​

Unless necessary, edits can be made without creating a new issue.

1. To initiate an edit, make your edits in the local copy of the Daedelus Wiki Repository.
2. Submit a new PR detailing the edit you made and why you made them. Note: For major revisions, please create a new issue detailing what has to be revised.

Link Management ​

Links are updated as soon as articles are made. When a writer creates a new issue for a new article, the parties involved should also discuss about the links and the articles to be included in the sub-directory.

However, the onus lies on the editor to discuss where to link things. Writers are not expected to know everything about the wiki's contents, much less as how the editors would.

Furthermore, link management should be done immediately after a Pull Request has been approved. Editors are expected to submit their own Pull Requests labeled as [link]Article Title.