Helping visitors navigate CF #522
Labels
enhancement
Enhancements to the website's presentation or contents
Comments
JonathanGregory
added
the
enhancement
|
This all sounds grat, thanks! One note:
symlinks can be a bit wonky with git -- make sure to test carefully. Alternatively, there must be a way to do a "Include" with md? Sorry, I'm not that up to speed on md. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Dear all
It has been pointed out by @DocOtak and others that it may not be clear enough where to start if you are new to CF and want to find something out or make a suggestion. If you go first to the CF website home page, I believe it should be obvious, and if it's not, we should make it so. On that page, or from that page, there is some background information, links to the documents which define the standard, resources for working with it, the CF GitHub organization, and the places to ask questions, make comments and propose changes. Rather than try to get all this clear and correct in more than one place, I propose we should try to direct all new arrivals to the home page. On the home page, new visitors will be particularly directed to Discussions if they want to ask a question.
In order to do that, I propose that
The
READMEin each repo (website/governance, conventions, vocabularies,discussetc.) should contain only minimal text of its own, just to say only what the repository is, and supplying links to the CF home page and other pages that are relevant to that repo. Avoiding redundancy will avoid theREADMEgetting out of date. TheREADMEis displayed when you visit the repo in GitHub e.g. https://github.com/cf-convention/cf-convention.github.io, at the bottom of the page, below the file listing, which as you see gives a link to the web site (as I advocate). So does the conventions repo https://github.com/cf-convention/cf-conventions, but it also contains other technical information that I don't think should be kept there. Instead, I would put it in other files that are linked to the website.We should create a similarly minimal
READMEfile for the GitHub organization, which would be displayed on https://github.com/cf-convention.In all repos that have no
indexfile, createindex.mdin the branch which is exported to Pages, with a redirection to the CF home page. There are several ways to do that, see e.g. https://stackoverflow.com/questions/5411538/how-to-redirect-one-html-page-to-another-on-load. I don't if they all work on GitHub Pages sites, but I have tested the HTML<meta>method in https://github.com/cf-convention/cf-convention.github.io/blob/main/testredirect.md, which containsSince that repo is exported to Pages to provide the CF website, its HTML version is https://cfconventions.org/testredirect.html, which redirects you immediately to https://cfconventions.org. Even neater (I think) is to make
index.mda symlink toREADME.md, and put the redirection inREADME.md. I've tested that works in my own GitHub. This would mean that if you open https://cfconventions.org/cf-conventions, for instance, you will get the CF home page. At present, in that case, you get anindexwhich is specific to the branch exported to Pages.Would those things be useful? What else could we do to point visitors in the right direction?
Jonathan
The text was updated successfully, but these errors were encountered: