This document describes how to contribute to the IOTA wiki.
We encourage everyone with knowledge of IOTA technology to contribute.
Thanks! ❤️
Ways to contribute 🔍
To contribute to iota-wiki on GitHub, you can:
- Report a bug
- Suggest a new feature or topic for the wiki
- Add a new feature or topic to the wiki
- Write content for the wiki
Report a bug 🐛
This section guides you through reporting a bug. Following these guidelines helps maintainers and the community understand the bug, reproduce the behavior, and find related bugs.
Please check the following list:
- Ensure the bug was not already reported by searching on GitHub under Issues. If the bug has already been reported and the issue is still open, add a comment to the existing issue instead of opening a new one.
Note: If you find a Closed issue that seems similar to what you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
To report a bug, open a new issue, and be sure to include as many details as possible, using the template.
Note: Minor changes such as fixing a typo can but do not need an open issue.
If you also want to fix the bug, submit a pull request and reference the issue.
Suggest a new feature or topic for the wiki 💡
This section guides you through suggesting a new feature or adding a new topic to the wiki. Following these guidelines helps maintainers and the community collaborate to find the best possible way forward with your suggestion.
Ensure the feature or topic has not already been suggested by searching on GitHub under Issues.
To suggest a new feature/topic, open a new issue, using the suggestion template.
Add a new feature or topic to the wiki 🔨
This section guides you through adding a new feature or topic. Following these guidelines helps give your feature/topic the best chance of being approved and merged.
Check if there is already an open issue or pull request (PR), related to your feature/topic.
Otherwise, your feature may not be approved at all.
To build a new feature/topic, check out a new branch based on the main branch.
Pull requests 📣
This section guides you through submitting a pull request (PR). Following these guidelines helps give your PR the best chance of being approved and merged.
Before submitting a pull request, please follow these steps to have your contribution considered by the maintainers:
-
A pull request should have exactly one concern (for example one feature or one bug). If a PR addresses more than one concern, it should be split into two or more PRs.
-
A pull request can be merged only if it references an open issue
Note: You don't need to open an issue for minor changes such as typos, but you can if you want.
-
All code should be well tested
The following is a typical workflow for submitting a new pull request:
- Fork this repository
- Create a new branch based on your fork. For example,
git checkout -b fix/my-fixorgit checkout -b feat/my-feature. - Commit changes and push them to your fork
- Target your pull request to be merged with
develop
If the maintainer approves the PR, it will be merged.
Note: Reviewers may ask you to complete additional work, tests, or other changes before your pull request can be approved and merged.
Write Content ✏️:
This document describes how to contribute and add content to the IOTA wiki.
We encourage everyone with knowledge of IOTA technology to share this knowledge with the community and help so help new people to get a better understanding and help the onboarding of new users.
Thanks! ❤️
The general menu structure of the WIKI website can be found in this Google shhet - you will see which content is still open to produce and clicking on the Link of the cell will directly open the content page in HitHub - Status of Work in Progress is currently this:
https://docs.google.com/spreadsheets/d/1GjYFRrNhloVyR6kSAVlMAEWadY3onRv6UFnpQGRl0Z8/edit?usp=sharing
We want every contributor to understand the purpose of the Wiki and our way of delivering content.
We want the Wiki to be the one single reference and source of truth and up-to-date information for everyone that needs information about the IOTA project. And the Wiki is meant as a gateway to provide everyone quick access to all information regarding IOTA.
We aim to deliver basic introduction content on the pages and whenever possible link the reader to more detailed content provided by the IOTA Foundation (Blog posts / Websites / Guides / Docs / GitHub). So you don't need to write an in-depth explanation about Mana for the Wiki if there is already very good up-to-date information available to where we can provide a link. So we would more give a general introduction to Mana in the Wiki and leave the detailed explanation in the Links.
But if you feel that the available information is insufficient, outdated, or too complex to understand for normal users, we are happy about detailed understandable content about a topic. As IOTA has been moving fast forward this might be the situation in many fields of the project atm.
We decided to split the WIKI into 4 major thematic areas that focus on the user/reader and the needs of those who visit the Wiki and we aim to deliver tailored content for that user group.
The Learn section aims to describe most of IOTAs core functions and technology. Content should be explained understandably for normal random users that have no, or just a small knowledge about IOTA. We want to welcome interested people and show them the way into understanding IOTA and get fascinated about it. Perfect would be if we could provide also links to external sources that deliver further detailed content in different levels of complexity. Also welcome to link to an IF YouTube video.
As we know the protocol has changed a lot and quickly we might not find up-to-date information, so we will write it ourselves.
Content for people that may be looking to use IOTA in their project / Company / Industry. Showcase of all the possibilities the protocol delivers, the several technologies developed for use cases. Explain and provide useful links to lead the reader into the project.
How can someone become active in the project? Where to interact with the community, how to engage with others or the technologies, and get a hands-on experience with IOTA.
Collect general info and link to Guides / POC's / Showcases / IF community sites. Create an interesting "how-to" explanation... everything that invites users: "oh yeah, I wanna do this"!
The gateway for Developers. Introduces the core functionalities on a more technical level and aims to bring developers directly into the correct framework for them to start working with IOTA. Also, deliver guides and tools that help to get started and to understand the concepts behind the protocol. This section will directly link to the underlying IOTA Docs and GitHub, so please provide correct links to the specific content in the IOTA Docs.
To add content to a page, you can use the implemented in-page editor. This will make it easy to use and you can write content with the known tools, similar as in a word or google doc. The editor translates this into a markdown file and creates a Pull Request to add this content into our GitHub Repository. We will check those Pull Requests and will approve it to be added, or will contact you if we have some suggestions to optimize the article or request changes.
We don't ask for perfection from everyone - it is a community-driven project and will grow and get better all the time, but we may have to change some things as we aim for a similar language and style throughout the whole website. This should give the readers the feeling that it is coming out of one source. So we will contact you on your GitHub account or comment directly in the Pull Request.
You can also create content directly in GitHub by forking the main branch and start editing the pages you wish to contribute. The Page documents will be found under https://github.com/iota-community/iota-wiki/tree/main/docs
To edit a document, click the pencil (edit this file) in the top right corner when viewing in GitHub.
This will open up the GitHub editor, so you can edit your file.
All pages are themed and styled automatically and follow a standardized format throughout the wiki.
Each page’s content is preceded by its front-matter information. This tells the wiki what it needs to know about the page to add it to the front-end in the right place. This does not need to be edited
---
id: my-doc-id
title: My document title
description: My document description
slug: /my-custom-url
---
# Header 1 – should only be used for page title/header using a single hash
## Header 2 – should be used for main sub-sections of the topic using a double hash
### Header 3 – should be used for internal sections of these sub-sections using treble hash
All page content should be written as standard text.
A paragraph can be created by leaving a double line break between two text blocks
Use single asterisk to make a word or sentence *italic*
Use double asterisk to make a word or sentence **bold**
Use triple asterisk to make a word or sentence ***bold and italic***
Use double tilde to ~~strike through~~ a word or sentence
To add a link to a page we use square brackets to contain the link text followed by round brackets containing the link address:
[this is a link](https://www.website.com)
To add an image to a page, we first need to upload the page to the image folder
Then on our page we can add the image using the same method as a link preceded with an exclamation mark:
To make an image a link, we can combine the two methods, by putting the link within the text section of the image code:
To create lists we use two different methods.
- Bullet point
- lists
- using a hyphen
1. Numbered
2. Lists
3. Using numbers
>To add a quoted or embedded text, we use the greater than symbol at the start of the section. To close off a quote we create a new paragraph.
There are two types of code entry we use `inline code` which is wrapped with single backticks
```Code blocks can be added in page where required
either to demonstrate function,
or to add an exclamation to a section,
by wrapping the section with treble backticks
### Line Divider
We can add a line divider to break up the page by adding 4 dashes
```----
Once you have completed your contribution goes to the bottom of the edit page to the commit changes section.
- In the title add the title of the page you have edited.
- Edited pagename.md
- In the description explain a little about your edits, whether it was fact correction, typo edits, or full page creation, page formatting, etc.
- Select create a new branch
- Name the branch after your name-pagename-edit
- Click commit changes
- This will open a pull request, where you can fill out the basic information for your updates.
- Then click the create pull request button
To keep our WIKI Project organized and help everyone understand the current state of work that's going on, we decided to use a Kanban Style Project Board. Everything related to content creation should be represented in this board. You will find it under the projects tab:
https://github.com/iota-community/iota-wiki/projects
In the board, we have created 5 fields that represent the life cycle of a content page till completion.
To do
Here are all pages that have not yet been started to work on. Pick the card of the content page you wish to create here and move it to the next stage by drag and drop into
In progress
Content that is currently been worked on by someone. As long as you are working and editing a page, leave the card here.
Ready for Review
As soon as you would be happy to receive a review of your work move the card here and open a Pull Request in "Draft" status. Request a review from one of the maintainers in your Pull Request or just ask in Discord for Feedback
add all links/content, ready for publishing
While your written content might be finished, the graphics, images or links to outside content or other Wiki pages might still need some fixing or contribution.
Complete
Content pages have been finalized and are ready to publish, Pull Request closed. Page can be added "as is" in the final Wiki version
Convert to issue
Every card in the Kanban can be converted into an open issue. You should use this feature. We can all work much better if we see which issues are currently open and which ones are closed and it helps us all to stay organized.
Once you have converted your Project Board card into an open issue, you can add some attributes to the issue that will structure our workflow
Assignees
You can assign an issue to yourself if you are working alone on your content, or to another member of the Team that you think can help or needs to have a look at that issue
Labels
Labels are an excellent tool to visualize an issue. They will show up in the Issues Main Overview and directly indicate what the issue is about. For content we use the "documentation" and "feature" labels.
Projects
Here you can assign an issue to a project. This should be already added if you have followed the steps above by using the Project Kanban Board. But you can also manage it here.
Milestones
Milestones can help you and others see if important progress has been achieved. You are free to add milestones that you may find important
Linked Pull Requests
As soon as you have opened a pull request for the content, link the issue to this pull request. When the Pull Request gets merged or closed, it will automatically also close this issue.
Enjoy contributing and if you have any questions or ideas send us an issue!