issue writing basics - yasufumi-nakata/mind-upload GitHub Wiki
The basics of turning a stagnant place into valuable work
This learning page is generated for GitHub Wiki. The public portal is managed on mind-upload.com.
- Updated: 2026-03-14 / Role: Issue writing basics
This page is a supplementary material for those who are writing an issue for the first time on Mind-Upload. Even if you don't have a complete solution, if you can write about where you stopped, what is missing, and what can be added to move forward, it will be a valuable issue.
What we introduce here is the minimum required to turn an issue into a workable change. Please be sure to return to the original page and check the individual technical claims and external collaboration conditions.
- Wiki: 5 paths to follow after participation/collaboration page - This is for people who want to see which page they go to after an issue.
- Wiki: What to do first in-house and external dependencies - Compensates for separation when external dependencies are mixed in an issue.
- Wiki: Basics of verification infrastructure - Explains why advance conditions and disconfirmation conditions are placed first.
- Even if you don't have a perfect solution, if you know where it stopped and what kind of deficiency it is, it will be a worthwhile issue.
- Advancing and disproving conditions make it clear how the issue ends.
- You need to separate external dependencies from changes you want to make now.
- Which issues will ultimately lead to great results depends on the research situation at the time.
- This wiki alone does not determine when externally dependent tasks are established.
An issue does not have to be a completed proposal. Rather, what's important is to leave a record of where you stopped, what's missing, and what could be added to move forward in a way that others can follow.
| Easy to misunderstand | Thoughts on this site |
|---|---|
| You can't write an issue unless you know the entire solution | Even if you don't have a solution, you can create an issue if you know where it stopped and what type of deficiency it is. |
| The bigger the proposal, the more valuable it is | Even if the issue is small, it is easier to move the issue if the correction position and completion conditions are clear. |
| You can also write all external dependencies in the same issue | Write the changes you want to perform in this repository and external dependent tasks separately. |
| Writing “difficult to understand” is enough | It will be easier to make corrections if you specify which word or paragraph on which page you stopped. |
| How to stop | Minimum things to write in an issue | Next page |
|---|---|---|
| I don't understand the term | A one-paragraph explanation of the term that stopped, the page location, and how it was misread. | Glossary / Content Hub |
| You have a strong claim but you can't see the conditions | Objective claims, missing conditions, what should be added to move forward, and what should be put on hold. | Verification / Roadmap |
| I found a document, but I don't know where to put it back | The title of the document, what you thought it would be effective for, and suggestions whether it is an unresolved problem, a proposal, or an issue. | A straight path back from literature to implementation and participation |
| Stops because experiment or IRB seems necessary | Write separately the preparations that can be made here and now, the items that depend on external sources, and the completion judgment. | In-house production and external dependencies |
| I don't know where to add it | What kind of information do you want to add, candidate pages, and why do you think it's there? | Basics of deciding where to place new information / Content Hub |
| Item | Contents you want to include even if it is short |
|---|---|
| Where did it stop | Information that shows the correction location, such as the target page, section, paragraph, term, table, etc. |
| What's missing | Types include insufficient definition, insufficient guidance, insufficient evidence, unknown state label, and confusion with external dependencies. |
| Changes to be made | I will now focus on one modification that can be implemented in this repository. |
| External dependent task | IRB, equipment, contracts, collaborative research agreements, etc., which cannot be completed by us alone. |
| Advance conditions | What needs to be added to make it ``improved''? |
| Rebuttal conditions | If something is confirmed, why not adopt the corrective policy or claim? |
| Weak writing style | Strong writing style |
|---|---|
| "This page is difficult to understand" | "I stopped because I couldn't understand the meaning of `benchmark` at the beginning of `verification.html`. It would be an improvement if there was a one-paragraph definition or a link to the wiki." |
| "I don't think it's possible with EEG alone" | "We believe that adding a comparison table of what can be said with EEG alone and what requires other modalities to `eeg_101.html' will reduce misinterpretation." |
| “I would like to do joint research” | "By specifying the one-page summary and minimum deliverables required before OpenNeuro collaboration in `issue.html#external-collaboration`, the first stage of external dependencies will take shape." |
- Making the problem too big: It is better to cut it down to the smallest units, such as one page, one term, or one conductor.
- Including external dependencies as completion conditions: Separate things that can be fixed on the spot from dependencies on other parties.
- Only advance conditions, no disproval conditions: It is also necessary to know what will happen and not adopt the corrective policy.
- Suggestion without a specific location: Checking the integration destination in Content Hub reduces duplication.
To return to the issue entrance, use Contribution Guide, to return to the branch after reading the participation page, use Five paths to follow after participation/collaboration page, and to return to the premise of condition design, use Verification.