Why Document?

1. Accessibility - nonexperts have an easier time learning and will become experts more quickly (they can then improve the eVOLVER).

2. Complexity - eVOLVER is a complex system and even experts may not have a complete grasp of all its parts.

3. Knowledge loss - when the designers of an undocumented part are no longer available, any troubleshooting or modification requires rediscovery of how that part works. (Even the designer of a part may forget how it works after some time).

When to Document

1. When creating a new feature in the base eVOLVER

2. No page about the topic exists and it could prove useful

3. Current documentation is out-of-date or insufficient

Background

Forum post titles should be a summary of the contribution.

Giving clear background information will help save a lot of time.

Please include the following information to promote effective discussion.

• eVOLVER software and hardware versions

• Expected behavior

• Actual behavior

• If about a bug / hardware failure - can it consistently be reproduced? If so, how?

• Screenshots are necessary

Example forum posts

Overview

The wiki is hosted on GitBook. For more information, check out their documentation.

Method 1: Open a Change Request on GitBook

When to use

Making more than a few edits to the Wiki

Information

Change requests are saved automatically

Your can access your change request draft at any time by clicking "Change Requests" in the upper left hand corner

For more information see the GitBook

Guide

1. Sign up for

2. Get an invite to the organization (email your Khalil lab contact)

3. Navigate to the eVOLVER Wiki by switching organization to Khalil Lab

1. Click "Edit" in the top right corner to open a Change Request

2. Use the GitBook to make your changes

   1. Try to match existing formatting

Method 2: Comment on GitBook

When to use

Suggestions, opening a discussion, or questions

Making only a few edits to the Wiki

Guide

1. Sign up for

2. Get an invite to the organization (email your Khalil lab contact)

3. Navigate to the eVOLVER Wiki by switching organization to Khalil Lab

1. See the GitBook

Method 3: Edit on GitHub

Less recommended because it does not translate Markdown

Does not require joining GitBook, only requires GitHub account

1. Click "Edit on GitHub" on the right hand side of the page you want to edit. (Or click on the three dots next to the title to show it)

2. .

Resources

Wikipedia's of guidelines

Content Structure

Page Content

What content goes in a page?

What content doesn't go in a page?

• Long blocks of code

  • Reference to a forum post discussing the code

  • Exception: where code is walked through line-by-line as an illustration

Links to subpages in a table of contents

Subpage Content

Content specific to subpages - anything not listed is the same as pages

Formatting

Links

Shortcuts (will not work in block edit mode): cmd + K (Mac) or ctrl + K (Windows)

Usage:

1. Pointing towards pages, subpages, or paragraphs on this wiki

Formatting:

1. , otherwise they will not be updated when the title or location changes

2. Internal links should be formatted using the inline pane

   1. This looks like (when text is highlighted before clicking on the inline text editing box above the cursor)

Usage:

1. Cite information as part of a page

2. Refer to a forum post on the topic - for questions, data, and detailed discussion

3. Refer to a specific place in a GitHub repository

4. NOT for referencing an eVOLVER Wiki page

Formatting:

1. Format like , not: