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

Split the contributing page #2210

Open
RDaxini opened this issue Sep 13, 2024 · 2 comments
Open

Split the contributing page #2210

RDaxini opened this issue Sep 13, 2024 · 2 comments

Comments

@RDaxini
Copy link
Contributor

RDaxini commented Sep 13, 2024

Is your feature request related to a problem? Please describe.
I think that this single contributing page in its current form may be overwhelming for new users; it certainly was for me not so many months ago 😅

Describe the solution you'd like
After reading some of the contributing pages on other projects (through the discussion in #2202), I feel like our contributing page would benefit from being broken up into several pages.

These pages would still all be under the same "Contributing" section, but they could be navigated through using the sidebar (like the user guide?)

In this way, we could keep the really basic basics on one (the first) page, then move other details such as code style, testing, virtual environments, etc. onto separate pages rather than just separate sections on the same page.

I think having the new pages split somewhere along the lines of the current sections would be a good starting point. I am interested to hear if anyone has any other suggestions for a structure, or for any entirely new sections.

Additional context
There are ongoing discussions on standardising the reference style (#2202) and standardising the typesetting of units (#2205). I think that the new (split) contributing section could include a style guide page with all of this new information on documentation style, as well as existing style information related to code style that we already have.

I am +1 for @AdamRJensen's suggestion to include a template function and I think the aforementioned style guide section would be a good place for this.

One potential new section (besides the style guide) could be a "Contact" page (later discussion in #2200) where readers are advised to create a new issue if they want to reach out. I am thinking a dedicated new page rather than a sentence in another page might be better because then a couple of screenshots showing how to create a github issue could be included to help new users.

If the community thinks this idea for restructuring would be useful, I'd be happy to have a crack at it.

@RDaxini RDaxini changed the title Split the contributing page Split the contributing page, add style guide Sep 13, 2024
@RDaxini RDaxini changed the title Split the contributing page, add style guide Split the contributing page Sep 13, 2024
@cwhanse
Copy link
Member

cwhanse commented Sep 13, 2024

If we keep a Testing page, I would put the detailed guidance (e.g., writing tests for ModelChain methods) into a further subdivision.

@kandersolar
Copy link
Member

+1 to splitting it up. I would keep the "This documentation" and "Code of Conduct" sections on the first page instead of splitting them into their own pages.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants