Direct new contributors to wiki page

fredjaya commented 1 year ago

The goal here is to make the wiki page the first, go-to resource for new contributors. This includes:

[x] From the c3dev readme, move the conda/non-conda install instructions to an appropriate place in c3dev wiki
[ ] Updating the c3dev readme to explicitly direct contributors to start with the c3dev wiki
[x] ~~Clarifying that cogent3 should be first installed (for pytest to work)~~ included in the readme, but not wiki
[ ] Maybe update the cogent3 readme as well

GavinHuttley commented 1 year ago

I think we need to sketch out the process more clearly in the c3dev README. In GitHub Markdown, the best way to include multiple "sections" with content but make it easier for a reader to quickly see what they need is to use the <details> and <summary> tags. Try pasting the following into a comment here and click on Preview

<details>
<summary> Use conda virtual environment</summary>

What you need to use conda
</details>

It should look like

Use conda virtual environment

What you need to use conda

Then the challenge is, what should be in the Wiki, versus in the README.

Perhaps the README should be for experienced developers (who don't need instructions on setting up conda and setting up ssh keys for their GitHub accounts, etc...). What do you think?

And we can update the cogent3 readme when we've tidied up c3dev.

fredjaya commented 1 year ago

I agree that the wiki should detail the step-by-step instructions for new devs. Thinking of reformatting/cleaning the wiki so it provides more (linear) guidance for contribution.

I like the bioconda and nf-core ones.

Not too sure with the c3dev README yet, but it might be more clear after the wiki is complete? The first line of the README should direct contributors to the wiki.

Test dropdown

cool 🐙

GavinHuttley commented 1 year ago

Those two examples are both generated by static-site generators. Just like our cogent3.org.

I think it's important to have editability of the pages without a full rebuild of the docs.

Perhaps thee's a way to "theme" GitHub wiki pages?

Nice!

🧗 drop down

cogent3 / c3dev

Direct new contributors to wiki page #37