Usage

The Wiki-First Process

1. A process problem comes up, typically while working on an issue or in communications, and information required to resolve the problem does not exist in the wiki
2. A crew member writes documentation to fill the gap in the wiki
3. A pull request is made to merge the updates into the wiki
4. Once merged, the change is announced by linking to the wiki page in the Discord server

Sometimes, updates are made while a meeting is happening. After the meeting is over, the updated documentation should be put into a PR as soon as possible.

Why Wiki-First?

Documenting in the wiki before taking any action may require more upfront time commitment because of the overhead of figuring out where to make the change and integrating that change into the wiki. However, the investment pays off in the long run as that information is needed and referenced again in the future. Keeping the wiki on hand while working is very similar to writing unit tests during the software development process.

A wiki-first approach also reduces duplication of process-related communication as long as the wiki stays up-to-date.

Usage Guidelines

How to use the wiki every day

Don’t stop yourself from doing something just because it’s not in the wiki

As the size of the wiki grows and as crew members join and leave, fewer people are going to know the wiki front-to-back, and so it’s natural to start working on something while inadvertently breaking the guidelines laid out in the wiki. When something like that gets noticed, a gentle and friendly reminder to refer to the guidelines should be encouraged. For example, say “It’s not a problem, but next time check out the following entry in the wiki.”

Seek answers to questions by referring to the wiki

You should typically expect to get answers to your questions by getting links to the wiki. Other crew members will do this because it’s efficient to share information this way to save a meeting. It’s also a sign that we’re documenting necessary information within the wiki. Being so-called “wiki-ed” is not meant to be a curt or rude gesture to shame you for not knowing the entire wiki—remember: nobody knows the entire wiki.

Take Comfort

Being so-called “wiki-ed” is not meant to be a curt or rude gesture to shame you for not knowing the entire wiki—remember: nobody knows the entire wiki.

In communicating an answer to someone else, always strive to link to the wiki. Remind others of this by asking “Can you please link to the wiki?”

When documentation does not exist for a question you have, make that update to the wiki

Such a situation reveals a gap in the knowledge base of the wiki that needs to be filled. After your question has been answered, discuss where it should be documented and who will do it. You can remind yourself and other people of this request by asking “Who will document this?”

The wiki represents what we do right now

The wiki doesn’t represent what we hope to do, what we should do, or what we used to do unless specifically mentioned. It should always depict what we do right now. To change how a process works at Coderos, you must make that change in the wiki. To propose a change to a process, make a pull request to change the wiki.

Organize wiki content by Function and Results

The wiki should be organized by function and result to ensure every entry in it has an appropriate place for easy maintenance.