You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
If you need help getting started using the model afer reviewing the [model documentation][doc-resources], the first point of contact with the CICE Consortium is the [Consortium Community Forum][forum].
The first point of contact with the CICE Consortium is the [Consortium Community Forum][forum].
This forum is monitored by Consortium members and also opened to the whole community.
Please do not use our issue tracker for general support questions.
The reason will be displayed to describe this comment to others. Learn more.
@apcraig I'm curious why you removed this link to the model documentation from the README ?
Personally I think the doc deserves a link in the README... (yes it's reachable from the "docs|passing" badge, but this is not clear for everyone).
The reason will be displayed to describe this comment to others. Learn more.
I didn't actually remember that there was a link on the README - my usual path to the doc is the 5 steps in @phil-blain 's list but with "Click the wiki link" instead of README for step 2. It makes sense to me to have it on the README page, since we'd prefer people look at the documentation before posting their questions on the forum. I also understand the desire to reduce the number of extra links. The main consideration, in my opinion, is whether users will understand which of the available links to follow in order to find what they are looking for, but in this case, having the doc linked directly might head off some unnecessary forum questions.
The reason will be displayed to describe this comment to others. Learn more.
I removed that link because it no longer exists. I'm fine including a link to the documentation, but all that link was doing was shortcutting one step in the 5 step process above. It pointed you to the model documentation section of the Resource Index. It's not like it took you directly to readthedocs. Also, that link was pointing to a particular section of a particular wiki page. It's the kind of link that is difficult to maintain as documentation evolves.
I know the documentation organization can be done a bunch of different ways. This issue, CICE-Consortium/About-Us#10 is working towards a bit of reorganization. I think one thing that comes out of the current discussion is that we have to decide what role we want the README.mds, Wiki Home Pages, and Resource Index to play. At this point, I'd like to propose we move this discussion to a new issue which I've just created, CICE-Consortium/About-Us#11.
The reason will be displayed to describe this comment to others. Learn more.
I should actually look at stuff before spouting an opinion! Now that I've looked at the README, I like it the way it is because it points to the primary resource locations. I might reorder them, putting the Resource Index second or maybe third (i.e. ahead of the forum link), but generally I think the references to documentation are good enough without the links themselves, for pointing people in the right direction. We've all developed our own "workflows" for finding stuff on the site, and it's frustrating when one that we're used to suddenly doesn't work. E.g. I've been looking for the github 'releases' page which used to be linked from the top of the 'code' page, and finally (!) found it now on the right-hand side (so at least it's still there, but I was a little irked that I couldn't find it at first - I don't think we made this change). The fact that there are several different paths is both good and bad - the balance between easy access and maintenance is what we're trying to optimize in the ongoing cleanup. I'll move to the new issue on this topic CICE-Consortium/About-Us#11 for remaining comments.
The reason will be displayed to describe this comment to others. Learn more.
Interesting to see everyone's workflow. I always use the Release table links for documentation and I've mainly trained myself to go straight to the Resource Index page for everything else. I don't know if a new user would do that though. I agree the the change irking you, Elizabeth, is something from the github side of things.
Why don't I send the consortium page to a colleague here and ask if she can find the documentation? A test!
The reason will be displayed to describe this comment to others. Learn more.
Just a quick comment. The updated github page layout is something I noticed right away too a week or two ago. A few times a year, github seems to modify the page layout. I think it's just part of using the site. I don't think we have or want to micro-manage it at this point. Hopefully all they're doing is rearranging things around a bit and creating new features. It would be bad if they start dropping features like the commits or releases pages.
The reason will be displayed to describe this comment to others. Learn more.
Interesting to see everyone's workflow. I always use the Release table links for documentation and I've mainly trained myself to go straight to the Resource Index page for everything else.
And I just type "readthedocs" into my browser window and click on the first remembered link, then I drop into my Projects space (I tend to stay logged into readthedocs and if I'm not, then I do have to login) and then I go directly to the documentation of interest. That won't work for people that do not have a readthedocs login and some ownership of the Consortium projects though. For everything else. I also go to the resource index and go from there.
I keep thinking that if we don't have an obvious flow that everyone generally falls into with regard to finding documentation, then our organization could be improved. But maybe that's not the right way to think about this.
The reason will be displayed to describe this comment to others. Learn more.
Okay, I asked one of the NCAR sea ice researchers who does not do code development to be a guinea pig. Directions: "If you go to the site (https://github.com/CICE-Consortium/CICE) are you able to fairly easily find how to get the documentation? (I'm specifically being vague because I want to see is someone not dealing with the consortium page day in day out can find it pretty easily."
Her response: "that was easy .....I found the README file and ended up finding documentation for many releases rather quickly (although I only checked out one!)"
So I suspect she went to the release table, not the resource index. But the point is users can easily find documentation pretty easily. Since that's our goal I don't personally think this is a priority to change.
55ca18bThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@apcraig I'm curious why you removed this link to the model documentation from the README ?
Personally I think the doc deserves a link in the README... (yes it's reachable from the "docs|passing" badge, but this is not clear for everyone).
Right now to find the doc you have to:
@duvivier @eclare108213 what do you think ?
55ca18bThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I didn't actually remember that there was a link on the README - my usual path to the doc is the 5 steps in @phil-blain 's list but with "Click the wiki link" instead of README for step 2. It makes sense to me to have it on the README page, since we'd prefer people look at the documentation before posting their questions on the forum. I also understand the desire to reduce the number of extra links. The main consideration, in my opinion, is whether users will understand which of the available links to follow in order to find what they are looking for, but in this case, having the doc linked directly might head off some unnecessary forum questions.
55ca18bThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I removed that link because it no longer exists. I'm fine including a link to the documentation, but all that link was doing was shortcutting one step in the 5 step process above. It pointed you to the model documentation section of the Resource Index. It's not like it took you directly to readthedocs. Also, that link was pointing to a particular section of a particular wiki page. It's the kind of link that is difficult to maintain as documentation evolves.
I know the documentation organization can be done a bunch of different ways. This issue, CICE-Consortium/About-Us#10 is working towards a bit of reorganization. I think one thing that comes out of the current discussion is that we have to decide what role we want the README.mds, Wiki Home Pages, and Resource Index to play. At this point, I'd like to propose we move this discussion to a new issue which I've just created, CICE-Consortium/About-Us#11.
55ca18bThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I should actually look at stuff before spouting an opinion! Now that I've looked at the README, I like it the way it is because it points to the primary resource locations. I might reorder them, putting the Resource Index second or maybe third (i.e. ahead of the forum link), but generally I think the references to documentation are good enough without the links themselves, for pointing people in the right direction. We've all developed our own "workflows" for finding stuff on the site, and it's frustrating when one that we're used to suddenly doesn't work. E.g. I've been looking for the github 'releases' page which used to be linked from the top of the 'code' page, and finally (!) found it now on the right-hand side (so at least it's still there, but I was a little irked that I couldn't find it at first - I don't think we made this change). The fact that there are several different paths is both good and bad - the balance between easy access and maintenance is what we're trying to optimize in the ongoing cleanup. I'll move to the new issue on this topic CICE-Consortium/About-Us#11 for remaining comments.
55ca18bThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Interesting to see everyone's workflow. I always use the Release table links for documentation and I've mainly trained myself to go straight to the Resource Index page for everything else. I don't know if a new user would do that though. I agree the the change irking you, Elizabeth, is something from the github side of things.
Why don't I send the consortium page to a colleague here and ask if she can find the documentation? A test!
55ca18bThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just a quick comment. The updated github page layout is something I noticed right away too a week or two ago. A few times a year, github seems to modify the page layout. I think it's just part of using the site. I don't think we have or want to micro-manage it at this point. Hopefully all they're doing is rearranging things around a bit and creating new features. It would be bad if they start dropping features like the commits or releases pages.
55ca18bThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And I just type "readthedocs" into my browser window and click on the first remembered link, then I drop into my Projects space (I tend to stay logged into readthedocs and if I'm not, then I do have to login) and then I go directly to the documentation of interest. That won't work for people that do not have a readthedocs login and some ownership of the Consortium projects though. For everything else. I also go to the resource index and go from there.
I keep thinking that if we don't have an obvious flow that everyone generally falls into with regard to finding documentation, then our organization could be improved. But maybe that's not the right way to think about this.
55ca18bThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Okay, I asked one of the NCAR sea ice researchers who does not do code development to be a guinea pig. Directions: "If you go to the site (https://github.com/CICE-Consortium/CICE) are you able to fairly easily find how to get the documentation? (I'm specifically being vague because I want to see is someone not dealing with the consortium page day in day out can find it pretty easily."
Her response: "that was easy .....I found the README file and ended up finding documentation for many releases rather quickly (although I only checked out one!)"
So I suspect she went to the release table, not the resource index. But the point is users can easily find documentation pretty easily. Since that's our goal I don't personally think this is a priority to change.