Wiki

Wiki: How to write your first issue

The basics of turning a stagnant place into valuable work

Mind Uploading Research Project

Public Page Updated: 2026-03-14 Issue writing basics

How to use this page

Read this first to avoid getting lost

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.

  • This page explains how to turn an ``I don't know'' moment into a fixable issue instead of discarding it.
  • We will organize the division of advance conditions, counter-evidence conditions, and externally dependent tasks from the beginning.
  • We will show you how to write each type, from minor terminology corrections to conditional design for strong claims.
Helpful next pages
Contribution Guide Verification base Public Content Integration Hub
Best for
People who are writing an issue for the first time, or who are unsure how to report something they don't understand.
Reading time
8-12 minutes
Accuracy note
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.

Relatively clear at this stage

What we know now

  • 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.

Still unresolved beyond this point

What we still do not know

  • 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.

Learn the basics

Check the basics in the wiki

What the wiki is for

The wiki is a learning aid. For the project's official current synthesis, success criteria, and operating rules, always return to the public pages.

Issue is not a complete answer but a moving question

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.

Thoughts you should know first

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.

Turn common stoppages into issues

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

Minimal template

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?

Difference between weak issues and strong issues

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."

Common mistakes

Mistake

  • 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.

Where to return next

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.