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

Improve the example header #358

Closed
Tracked by #383
maximlt opened this issue Feb 2, 2024 · 1 comment · Fixed by #432
Closed
Tracked by #383

Improve the example header #358

maximlt opened this issue Feb 2, 2024 · 1 comment · Fixed by #432

Comments

@maximlt
Copy link
Contributor

maximlt commented Feb 2, 2024

@jbednar has expressed some concerns with the design of the example header that doesn't convey enough that an example is closer to a blog post than an updated resource.

image

@jbednar
Copy link
Contributor

jbednar commented Feb 4, 2024

Right. I'm worried that we are giving the wrong message to our users, setting up expectations that we cannot fulfill. I think users expect project docs to be kept up to date and evolve with the project, while they are aware that magazine articles, blog posts, Stack Overflow answers, and similar items do not get updated. I think we should put in clear cues to the reader that the examples in this website and repository are of the latter type: created at a certain time, and thus naturally going out of date over time, with no promise of being updated when new releases are made. That way this site can have more elaborate, complex examples than the simpler ones on the individual project websites, without us gradually being unable to make progress because of having to update examples all the time.

E.g. here's a blog post from @ahuang11 about hvPlot:

image

It's clearly labeled as coming from a specific human being, and on a specific date, so no one would expect it to have the latest hvPlot syntax if they run across it several years from now. Compare that to the header above, where the header info (useful as it is!) appears to be some bookkeeping stuff, not clearly declaring the semantics of this page. There's no explicit author (though I can deduce from the username that I wrote it), and the dates on it are more like a website's date tagging than like a blog post or magazine articles.

To address this issue, I propose that we:

  • Shorten the current header to all fit on a single line in most cases, so that it's truly fading into the background
  • Maybe even remove the box and/or make the text dimmer and italic so that that info is very clearly "about" the page rather than in it
  • Maybe remove "Last" since it conveys a responsibility for updating that I don't want our group to take on; we do update it some times, but there's no promise to do so!
  • Add an explicit author after Attractors. I'm guessing this would need to be done by hand, but since we're updating things right now, that seems doable, and it wouldn't need to change; other people can add themselves as explicit authors if they feel like they've done enough to it, if they wish.
  • Add an explicit date after the author, which would be an initial date and then never updated unless someone explicitly wished to convey that it's a new example.

Does that sound ok to anyone else?

@maximlt maximlt mentioned this issue Apr 21, 2024
21 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants