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

Add a link to the discussion forum in each of our repositories #835

Open
choldgraf opened this issue Oct 6, 2022 · 2 comments
Open

Add a link to the discussion forum in each of our repositories #835

choldgraf opened this issue Oct 6, 2022 · 2 comments
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@choldgraf
Copy link
Member

Context

We recently got some great feedback about challenges to contributing to the project. One piece of feedback was that there is not much visibility to the discussion form (link below):

There are only a few places where we link to this forum, and it's not easy to get there from every other documentation site.

Proposal

We should provide a link to the discussion forum on every page of our documentation. This could either be an "icon" or it could be a toctree-style link. I think there are two potential ways we could do this:

  • Create an "executablebooks theme" and deploy that in our documentation sites. This way we could unify the look and feel of our documentation across all projects, and include some standard information about each in a shared header. This is similar to what the Dask documentation does.
  • Hard-code an icon or link to the docs in each documentation page. This would give us more flexibility to do it as we wish, but it would also be duplicated work.
@kai-tub
Copy link

kai-tub commented Oct 6, 2022

I very much like the unified Dask style.
And I think their community page also provides a nice template to better communicate where to find help for what.
Although, I would prefer to have a TL;DR section at the top that gives a couple of examples with links, like:

  1. Do you want to report a bug? --> Issue section
  2. Do you have a general question and would like some help from the wider community? --> Discussion Forum
  3. Do you want to let others know what you've create --> Split by project (book page) or community page or show-and-tell page
  4. Have you used our tools and would like to help grow the community? --> Discussion Forum open questions
  5. Do you have suggestions regarding the UI?

And possibly with examples.
Especially providing a 'real' UI example tells a user how "detailed" the suggestion should be and how pedantic one can be.
UI feels like a sensitive/controversial topic, so here would be a good place to set the 'expectations'.
Potential feedback could range from dislikes about used CSS frameworks (Bootstrap 👀) up to preferences about rounded edges vs. straight edges.
Because of this wide range, an example could help to make it easier to start a conversation about UI decisions.
Is ok, to be the guy that says: "Uhmmm, actually according to the HTML spec, you aren't using accessible color contrast ratios."
or "Uhmmm, your layout X looks broken on browsers with 150% zoom (referring to classic px/em issues)".

Just my 5ct :)

@rowanc1
Copy link
Member

rowanc1 commented Oct 7, 2022

Thanks @kai-tub for kicking off these improvements, really value the input and thank you for jumping in! :)

I have put together a first pass of a github welcome page, which I think is a quick win that can point to the discussion forum as well as showcase a few of the tools and ways they fit together. See:

I have tagged @choldgraf and @mmcky in helping to review the text, but feel free to jump in there if you have some comments as well.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

3 participants