Role of README.mds, Wiki Home Pages, and Resource Index

[apcraig]

The current README.mds, Wiki Home Pages and Resource Index are highly redundant. Can we clarify the role that each of these top level pages should play.

[apcraig]

There are many ways to handle documentation organization. I think there is benefit with regard to maintenance and usability with keeping the organization fairly clean and clear without a lot of redundancy.

One idea would be to use the Resource Index as the main page and to consider moving this to either the About-Us Wiki Home page or even to the About-Us README.md (although I am not that fond of actively evolving documentation being part of the basic repo).

Another idea is that we could have something like this on all the README.md and Wiki Home pages,

"Welcome to the ... (ie. CICE repository). You can find documents that describes the model science, usage, and releases; the Consortium processes and interaction; and many other things on the [Resource Index page][https://.../Resource-Index]."

Another option might be to take the Icepack and CICE sections of the Resource Index and migrate them to the README or Wiki Home page of the Icepack and CICE repos. That would break apart the Resource Index a bit and create an extra level of organization for some of the documentation but might also work better with the structure of the Consortium github space. If we did that, the Resource Index would point to the Icepack and CICE "index" page for Icepack and CICE stuff while the Icepack and CICE "index" page would point to the Resource Index page for non Icepack/CICE stuff.

Finally, if we do want for the Resource Index, the README.mds, and the Wiki Home pages to continue to act as they do now, maybe we can clarify what we expect to be on each page and try to organize the documentation/links so they are pretty stable and consistent.

[eclare108213]

Lots of good ideas here. I prefer keeping the single Resource index as just that, not a readme or wiki home page. In my opinion, we should be able to limit the redundancy of active links while still pointing people in the right direction via the informational text around them. For example, the readme says that links to the documentation are found in the version index (for specific versions) and in the resource index (general). Both the readme and the wiki home pages can and should point primarily to the resource index, but other locations that might not be so obvious for users to look for (like the forum) also need to be prominent. From that point of view, the links to the main wiki and to the version index don't necessarily need to be on the readme page, although I'm not opposed to them. I do also think that we should limit the searching and number of hops that are required, and so I think the resource index should be pretty comprehensive (like a good index in a book); the entries don't all need to be active links, but the info on what's available and where to find it needs to be there. That's my opinion.

I totally agree with the last paragraph above. Perhaps a few of us should put our heads together to map out a final plan. We're getting closer and @apcraig has done the analysis to understand what we've had, we just need to talk it through.

[apcraig]

I agree the resource index should be a comprehensive index without a lot of words so it's mostly a quick reference to everything.

With regard to the READMEs, maybe one way to think about this is "use cases". I'm particularly thinking about the Icepack, CICE, and AboutUs repos. The test-results repo is it's own thing. And I think we can update the CICE-svn-trunk repo separately after we organize the rest of it.

For a new user, the first link on the CICE and Icepack README should be to a getting started page. That page should be the AboutUs README. I think the AboutUs README is pretty good now, but should be expanded to provide a broad overview of the Consortium organization and then how to take the next steps. It should be descriptive with links. Alternatively, we could use an AboutUs wiki page or the AboutUs wiki home page for this descriptive getting started document.

For an experienced user, we want all READMEs to point to the Resource Index (and wiki home page?).

For all users, we want all READMEs to point to the forum to encourage and remind users of it's important role.

For legal reasons, we want the README to point to the License and Distribution Policy.

That means the Icepack and CICE READMEs should point to

• AboutUs README (getting started)
• Forum
• Resource Index
• Wiki Home Page (maybe)
• License
• Distribution Policy

I'm still struggling with the role of the wiki home page. The READMEs are what people will almost always see first. And from there, they might jump to the Resource Index. So, should the wiki home page

• play a similar role to the README? if so, why?
• be a brief index to some documents just on that wiki?
• be small or large, descriptive or listed, of local or global breadth?

I propose that the Icepack/CICE wiki home page provide a few of the most general, useful links plus duplicate some of the main links in the Resource Index for each model. So that might be

• Forum
• Resource Index
• Version Index
• Recent Changes
• Input Data
• Readthedocs master documentation

I think the AboutUs wiki home page is pretty OK at this point.

I think we're pretty close to this right now. Finally, I think one important issue to consider is whether we want the README.mds to be fairly static. I think the answer is yes in CICE and Icepack. We don't want to be constantly updating those READMEs as it impacts our model development/PR flow since they are part of the Icepack/CICE repo. For the AboutUs, I don't think it's a problem. I think we can just edit the README directly or we can create PRs in AboutUs if we want. Repo management is not an issue in AboutUs. I think that means it's OK to make the AboutUs README be the getting started page and for it to evolve regularly. But again, if we feel that's not how we want the AboutUs README to work, the getting started page could be the AboutUs wiki home or a separate AboutUs wiki page and we'd probably make the AboutUs README play a similar role as Icepack and CICE.

[eclare108213]

I tend to agree that the READMEs are likely to be the first entry point with any information, and so they should include the fundamental links like forum, resource index, license etc. Also, keep in mind that someone looking at the README in their clone will only have access to it (links might or might not work from supercomputing centers, for example), and so the information there ought to be relevant for that use case. The CICE/Icepack wiki home pages at the moment contain some of the same information as the READMEs. I could see these going either way, being more descriptive (not necessarily with more links) or becoming just a list of links, a table of contents if you will, for that repo. In fact, the wiki home pages could function as a "site map" of the Consortium's resources for that repository, like some other web sites have. That might be difficult to maintain, though, unless it's still kept at a fairly high level, so I'm not crazy about the idea. Personally, I like being able to see everything (at a high level) at once, so that I can choose the link that seems most appropriate, and that's really the role played by the resource index for all of the repositories together. The wiki home pages could just stick with general, descriptive information (think of them as the "abstract" for our github+zenodo+readthedocs+etc "publication"), and point to the resource index for further links. But honestly, these pages all look okay to me. Re-reading @apcraig's comments above, I think we're pretty much on the same page (to use a confusing metaphor). I'll repeat what I said above, that a few of us should just get together and map out a final plan based on @apcraig's analysis of links, etc.