-
Notifications
You must be signed in to change notification settings - Fork 24
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
Comments
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: 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:
Does that sound ok to anyone else? |
@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.
The text was updated successfully, but these errors were encountered: