Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Shorten Contributing Guidelines by introducing subsections that can be collapsed #81

Open
likeajumprope opened this issue Jun 17, 2021 · 3 comments
Assignees
Labels
enhancement New feature or request OHBM brainhack 2021 Tracking for proceeding write up

Comments

@likeajumprope
Copy link
Collaborator

Is your feature request related to a problem? Please describe.
The Contributing Guidelines are very long.

Describe the solution you'd like
Divide the contributing guidelines into subsections that can be collapsed., as seen here: https://github.com/htwangtw/depersonalisation

Describe alternatives you've considered
Alternatively, we could improve the structure of the Contributing Guidelines.

Additional context
For an example of how the output should look like, see here:
https://github.com/htwangtw/depersonalisation

@likeajumprope likeajumprope added the enhancement New feature or request label Jun 17, 2021
@jhlegarreta
Copy link
Collaborator

Particularly, I find the git/repository cloning related instructions (e.g. how to set the upstream remote, pulling changes) something that, even if useful, is required in virtually any git-based project. So I would shorten those passages.

Same applies to the paragraphs about creating a virtual environment: we could just mention that a virtual env is the preferred options to install the dependencies: e.g.

(...)
1. If you are using `venv` or `virtualenv` create a virtual environment. Once created and activated, do a
pip install -r requirements.txt
2. Conda-related option (...)

and put the links to the docs of venv or virtualenv.

Also, I think the sections that come after Bibliography could be put somewhere else, since they are not strictly related to the guidelines to install the requirements or build the book, but are rather about features of a book/jupyter notebook.

@htwangtw
Copy link
Collaborator

I am in favour of a collapsable section over simplifying the instructions with link to the official doc. After interacting with some people at Brainhack, the new people who approached me mostly need detailed guidance on set-up. It would be useful to have all info in one place to point people to.

Talking about set-up, we still need some help to have some instruction working for windows, see #74

@likeajumprope
Copy link
Collaborator Author

will have a look

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request OHBM brainhack 2021 Tracking for proceeding write up
Projects
None yet
Development

No branches or pull requests

3 participants