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
Sign up for
Get an invite to the organization (email your Khalil lab contact)
Navigate to the eVOLVER Wiki by switching organization to Khalil Lab
Click "Edit" in the top right corner to open a Change Request
Use the GitBook to make your changes
Try to match existing formatting
Be sure to update your change request if you are prompted, because that means someone else has merged a request elsewhere. It also means some functions won't work until you update.
Method 2: Comment on GitBook
When to use
Suggestions, opening a discussion, or questions
Making only a few edits to the Wiki
Guide
Sign up for
Get an invite to the organization (email your Khalil lab contact)
Navigate to the eVOLVER Wiki by switching organization to Khalil Lab
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
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)
.
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:
Pointing towards pages, subpages, or paragraphs on this wiki
Formatting:
, otherwise they will not be updated when the title or location changes
Internal links should be formatted using the inline pane
This looks like (when text is highlighted before clicking on the inline text editing box above the cursor)
Usage:
Cite information as part of a page
Refer to a forum post on the topic - for questions, data, and detailed discussion
Refer to a specific place in a GitHub repository
Formatting:
Format like , not:
Follow our formatting guidelines, especially for links
Once finished with changes, click "Submit for review"
Your request will be reviewed and possibly edited before being merged with the Wiki
Or this: eVOLVER Community (when no text is highlighted before clicking on the inline text editing box above the cursor)
Block-level internal links are very large and should not be used (such as the following):
Accessibility - nonexperts have an easier time learning and will become experts more quickly (they can then improve the eVOLVER).
Complexity - eVOLVER is a complex system and even experts may not have a complete grasp of all its parts.
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
When creating a new feature in the base eVOLVER
No page about the topic exists and it could prove useful
Current documentation is out-of-date or insufficient
Documentation about optional extensions (optogenetics, biosensing) to the eVOLVER should be collected and added to the Wiki after publication.
Making a Forum Post
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?
