search

CICE-Consortium / About-Us

Background and supporting information for the CICE Consortium
2 stars 6 forks source link

Consortium Documentation Organization #10

Open apcraig opened 4 years ago

apcraig commented 4 years ago

I am creating this issue to allow us to review our current documentation organization and discuss potential changes. I have attached a pdf that attempts to show our current organization both in outline form and via some sort of primitive dependency graph. The outline syntax attempts to identify unique pages and links (->). An "S" at the front means it's on the sidebar. The dependency graphs are generated for the CICE (page 2), Icepack (page 3), and About-Us (page 4) repos as well as all together (page 5). The arrows point from the document to the link and should be darker at the source to help highlight the direction of the dependence. Page 6 proposes some updates to the About-Us organization and page 7 shows the dependency graph of that. To help make it easier to see, page 8 and 9 show the About-Us dependency graph for the current and proposed About-Us structure with links from the Resource Index page removed (because it points to everything).

Attachment is Consortium-Doc-Org.pdf

My proposal addresses a number of different issues that I hope will make the documentation easier to navigate and understand as well as maintain. I am initially proposing some changes to About-Us organization, but what I propose also covers some other issues like clearly identifying format, number, and reuse of documents in multiple repos (like Copyright/License/COC)

I think the main points I've highlighted on page 6 are

I'm not suggesting all of this is necessary or that it's comprehensive. Anyway, I thought this might be useful to do at this point since our documentation and process is maturing, and it might be good to try to review what we have.

eclare108213 commented 4 years ago

I agree with most of these suggestions. I do have a few comments on specific items:

  • Should we combine news and news archive?

Fine with me, but there was a reason that we separated them. @duvivier do you remember what that was?

  • Move FAQ to cesm forums

Good idea. It will take a bit of work to make each section a separate entry. Or do we want to keep an FAQ separately, somehow?

  • Manage links to external sites better so there are fewer links to maintain. For instance, create a document that links to cesm forum and have other documents point to the document vs have all documents point to cesm forums directly. This is much easier to maintain (both the link and description of cesm forum exists in only one place).

It might be annoying for users to have to make 2 jumps instead of one, especially if their internet connection is slow (like mine).

  • Have sidebar links and document names agree better to reinforce a “single” name

Choose the more succinct name, please. Let's iterate on the list.

  • Group together documents and topics where possible.
  • Organize Governance documents better both in terms of stuff that needs to be in each repo and stuff that can be centralized

  • Decide what documents needs to exist in all repos and/or on wikis and decide format, recommend text or .md to make things easier to change

    • License?
    • COC?
    • ?

The License and Distribution Policy need to be kept together. LANL wouldn't let me put the distribution policy in the License file, and I had to argue a bit to get them to allow me to change the wording enough to reference it. These need to be present in each code repository so that they are downloaded when the code is cloned.

It's fine with me to move all of the governance documents from the main repo to the wiki, but I might leave them where they are, as pdf, and reference them from a common wiki site. Part of the reason for using pdf for the Governance documents is to make them less easy to change. Any changes must be approved by the Executive Oversight Board, and the documents have a formal change log (or at least a date) at the bottom. It turns out that pdf is not that difficult to change, but it does take some effort, and changes to the governance should be done very deliberately.

  • Identify and reduce number of current copyright statements. Can we point and/or reuse? Can we have single format? Can we implement a tool that quickly updates all? Currently, they exist in

    • License in each repo
    • icepack/icepack_inlc.F90
    • icepack/icedrv_main.F90
    • icepack + cice doc conf.py
    • icepack + cice doc copyright.rst
    • cice every driver in either CICE.F90 or CICE_copyright.txt (inconsistent)

I agree that we should make these consistent. The wording was dictated by LANL. LANL says that the copyright should appear at the top of every file that is released. I've taken a compromise approach, ensuring that it appears at the top of the code tree for each of the primary configurations and releases: the license in each repo and copyright statements in the top-level drivers for both CICE and Icepack, and also in the main interface module of Icepack. It probably does not need to be carried in the documentation, just have a pointer to the official file.

I'm not suggesting all of this is necessary or that it's comprehensive. Anyway, I thought this might be useful to do at this point since our documentation and process is maturing, and it might be good to try to review what we have.

Thanks for spearheading this, @apcraig.

duvivier commented 4 years ago

@apcraig Overall I agree with suggestions. Realistically we'll tick them off slowly over time as I get a chance to deal with them.

I agree with most of these suggestions. I do have a few comments on specific items:

  • Should we combine news and news archive?

Fine with me, but there was a reason that we separated them. @duvivier do you remember what that was?

I think we just wanted to move things out of the "news" and into the "archive" on a regular basis when there were things to report. Obviously the "news" section doesn't get additions very often. I don't think we need to keep them separated. We may even want to discuss how best to use/maintain this section.

  • Move FAQ to cesm forums

Good idea. It will take a bit of work to make each section a separate entry. Or do we want to keep an FAQ separately, somehow?

Also makes sense. I don't think it will be too bad to have each of these a separate issue. I think we can give them a special "FAQ" tag and pin them at the top of the forums so they're easier to find. We could combine some (e.g. contacting and contributing to the Consortium into just "interacting with the Consortium")

  • Manage links to external sites better so there are fewer links to maintain. For instance, create a document that links to cesm forum and have other documents point to the document vs have all documents point to cesm forums directly. This is much easier to maintain (both the link and description of cesm forum exists in only one place).

It might be annoying for users to have to make 2 jumps instead of one, especially if their internet connection is slow (like mine).

I'll look into what could easily be removed/combined. I agree too many links is a pain and in other documents I've been helping put together I've been noticing this more and more. There are old links to people's email addresses who are no longer associated with projects, etc. and its a good reminder of how hard it is to maintain all this sort of stuff long term.

  • Have sidebar links and document names agree better to reinforce a “single” name

Choose the more succinct name, please. Let's iterate on the list.

I'm not sure I understand this. Do you mean that the name in a sidebar link doesn't always match the "name" when you click on the link?

  • Group together documents and topics where possible. Yep

  • Organize Governance documents better both in terms of stuff that needs to be in each repo and stuff that can be centralized

  • Decide what documents needs to exist in all repos and/or on wikis and decide format, recommend text or .md to make things easier to change

    • License?
    • COC?
    • ?

The License and Distribution Policy need to be kept together. LANL wouldn't let me put the distribution policy in the License file, and I had to argue a bit to get them to allow me to change the wording enough to reference it. These need to be present in each code repository so that they are downloaded when the code is cloned.

I heard from Dave that he got flak from someone at NCAR about the COC not being in each repo recently.

It's fine with me to move all of the governance documents from the main repo to the wiki, but I might leave them where they are, as pdf, and reference them from a common wiki site. Part of the reason for using pdf for the Governance documents is to make them less easy to change. Any changes must be approved by the Executive Oversight Board, and the documents have a formal change log (or at least a date) at the bottom. It turns out that pdf is not that difficult to change, but it does take some effort, and changes to the governance should be done very deliberately.

  • Identify and reduce number of current copyright statements. Can we point and/or reuse? Can we have single format? Can we implement a tool that quickly updates all? Currently, they exist in

    • License in each repo
    • icepack/icepack_inlc.F90
    • icepack/icedrv_main.F90
    • icepack + cice doc conf.py
    • icepack + cice doc copyright.rst
    • cice every driver in either CICE.F90 or CICE_copyright.txt (inconsistent)

I agree that we should make these consistent. The wording was dictated by LANL. LANL says that the copyright should appear at the top of every file that is released. I've taken a compromise approach, ensuring that it appears at the top of the code tree for each of the primary configurations and releases: the license in each repo and copyright statements in the top-level drivers for both CICE and Icepack, and also in the main interface module of Icepack. It probably does not need to be carried in the documentation, just have a pointer to the official file.

I'm not suggesting all of this is necessary or that it's comprehensive. Anyway, I thought this might be useful to do at this point since our documentation and process is maturing, and it might be good to try to review what we have.

Thanks for spearheading this, @apcraig.

Most of these governance docs and wording I haven't taken the lead on because I had the impression LANL was very specific about how it needed to be done. So @eclare108213 will be the better authority here for how and what can be done.

apcraig commented 4 years ago

In the spirit of less-is-more, I'm proposing an update to the Resource Index Page,

https://github.com/CICE-Consortium/About-Us/wiki/Resource-Index-Update

I believe no information has been lost in this reorganization, it cleans up a number of redundant links, and provides the information in a more compact form. It also creates more consistency between the resource page and the sidebar names. I also modified the overall organization and created separate high level Icepack and CICE sections. I think this is more consistent with the overall organization of the project and may also match up better with how users might want to access the information. Please have a look and let me know if this is a direction we might want to go, how it could be improved, or if you prefer to just stick with what we have for now.

I also migrated the existing "Organization and Governance" documents links onto that wiki page, https://github.com/CICE-Consortium/About-Us/wiki/Consortium-Organization-and-Governance and merged the News and News Archive pages and then deleted the archive page for now. We can always split again later if we feel it's needed.

eclare108213 commented 4 years ago

I like these changes, except the DOI links on the resource index aren't what we want, in my opinion. There is an issue to deal with this, specifically: https://github.com/CICE-Consortium/CICE/issues/465

apcraig commented 4 years ago

I'm glad to see #465. I was looking at the DOI stuff and didn't understand what was happening (or what was supposed to happen) which is why I added a "check this" on the new page I created. I agree we need to clarify DOI referencing.

apcraig commented 4 years ago

In the spirit of less-is-more, I'm proposing an update to the Resource Index Page,

https://github.com/CICE-Consortium/About-Us/wiki/Resource-Index-Update

I believe no information has been lost in this reorganization, it cleans up a number of redundant links, and provides the information in a more compact form. It also creates more consistency between the resource page and the sidebar names. I also modified the overall organization and created separate high level Icepack and CICE sections. I think this is more consistent with the overall organization of the project and may also match up better with how users might want to access the information. Please have a look and let me know if this is a direction we might want to go, how it could be improved, or if you prefer to just stick with what we have for now.

I also migrated the existing "Organization and Governance" documents links onto that wiki page, https://github.com/CICE-Consortium/About-Us/wiki/Consortium-Organization-and-Governance and merged the News and News Archive pages and then deleted the archive page for now. We can always split again later if we feel it's needed.

@duvivier If you have a chance, I'd like to hear your thoughts on the updated Resource page before possibly updating.

duvivier commented 4 years ago

@apcraig I'll look it over this weekend. I hope that's okay. Sorry to be MIA

apcraig commented 4 years ago

@duvivier, no rush and no problem. Thanks!

duvivier commented 4 years ago

@apcraig I think this new page looks awesome. It's easy to find what you might be looking for and looks a lot cleaner. Thanks for putting this together. Sorry I've been MIA.

A few comments/questions:

Thanks again. This is looking great.

apcraig commented 4 years ago

Thanks @duvivier. I have updated the Resources page now. I also tried to make some more progress on a "single name". There is probably a bit of work to do. It's a little tricky because when you change a file name, you can break links. I tried to click on everything and did fix what links were broken including in the README.md's of CICE and Icepack. The old Resources Index is still there and renamed to Resource Index Old Version1. We can delete that in a few months assuming we don't find any issues.

I think we discussed migrating the FAQ to the Community Forum, but I'm not sure we decided 100% nor have we assigned anyone to do that. We should also decide whether we want an FAQ topic that contains several questions and answers. I think we risk creating some chaos if users start posting to it. Another option is to have individual topics for individual questions that each have FAQ in their title. I think I like that better. But it's something we need to sort out.

duvivier commented 4 years ago

Great. I just looked through a bit more. I'm fine waiting for now to move the FAQ or maybe deciding not to.

I noticed the sidebar on the new "About Us" wiki has "CICE Version Index" and "Icepack Version Index" that link to the CICE and Icepack wikis. However, on those wikis we call the pages "CICE Releases" and "Icepack Releases" in the sidebar. Maybe these names should be changed sooner rather than later. I got confused for a sec and I helped make these pages! WDYT?

One page I've never really liked is the "CICE Recent Changes" and "Icepack Recent Changes" pages. I guess the reason why is that I feel like we do code releases often enough that they feel irrelevant and I often don't think to update them. However, now that I type this I think that @eclare108213 said she uses this as a template for the release notes. So maybe it is important to keep them. I just feel like they're a little confusing and we should be encouraging most people to just use released versions of the code for applications. Alternately, could we put the information about major changes since last release below the "Version Index" tables? That would reduce a page and also have the information right there about any additional changes since the table versions. Again, WDYT?

eclare108213 commented 4 years ago

I like "... Releases" rather than "... Version Index". Seems more intuitive to me, unless there are versions in the index that aren't somehow released. I don't think that's the case.

I'd prefer to keep the Recent Changes pages - they are a template for the release notes, and they also are a way for me to keep track of what's changed, to help plan the next release.

I just went to the Resources page to try to jump to our zenodo community, and I didn't find the link at all. We use zenodo for release DOIs, but it has other resources on it too and in fact is a place where community members can upload related stuff (like papers, plots, etc). This doesn't seem to be documented. https://zenodo.org/communities/cice-consortium

eclare108213 commented 4 years ago

... and now I'm not finding a link to the deprecated code page. Maybe I don't know how to use the Resources page anymore, but it seems like things are maybe buried a little too much.

duvivier commented 4 years ago

... and now I'm not finding a link to the deprecated code page. Maybe I don't know how to use the Resources page anymore, but it seems like things are maybe buried a little too much.

439 indicated to me that we hadn't yet settled on the deprecated code page and where we should link from. Did I miss that being settled earlier also?

As for "Releases" vs. "Version Index", I don't really have a preference just consistency. If you prefer releases that is fine by me.

I am fine keeping "Recent Changes". Just was curious if it could be merged with the "Releases" pages. I know you use it for notes, so I didn't think eliminating it entirely was a good option.

And you are right, the zenodo community isn't linked. I'd vote to put that right above the "community" forum and under users and citations.

eclare108213 commented 4 years ago

Ah, could be that we didn't link the deprecated code page yet, even though I've sent email to the users about it. Let's add it somewhere. That needs to be fairly prominent, in my opinion - people downloading the code ought to be warned...

duvivier commented 4 years ago

I just linked the Zenodo community and Deprecated features page on the Resource Index. I did see that we link to the CICE and Icepack DOI pages, which are zenodo links, but it wasn't super clear from the title that it linked to zenodo rather than the release tables.

I changed the sidebar title to "CICE Releases" and "Icepack Releases" in the associated wikis, but I didn't change the title of the page from "Version Index" because that directly affects the URL and I didn't want to break it without a careful check of where it could be broken (README.md and such) and I don't have the time right now to do that careful check.

apcraig commented 4 years ago

I agree that "Version Index" is not a good name. I'm sure I was the one that came up with that. I also am not sure "Releases" is good mainly because github already provides a "Releases" Page (https://github.com/CICE-Consortium/CICE/releases) that is different from our custom page. I have a couple ideas, I propose we rename "Version Index" to "Release Table" thereby differentiating the github "Releases" page and our "Release Table" page. The other idea would be get rid of our "Version Index" page complete and incorporate the DOI, test, results, etc links into the Releases page that already exists. Personally, I think it's nice to have the table (aka Version Index) as it's makes the history and links very accessible to users, but I'm happy to think about getting rid of it. If we agree on the naming convention and how to proceed, I'm happy to go thru and update the page names and all links (that I can find).

With regard to the DOI stuff, this is something that I continue to be unclear about how to best reference. We have the "Version Index" that points to the release DOIs. This is important. We also have a link on the Resources page that points to the most recent DOI of Icepack and CICE. My preference would be to get rid of that. I carried that over from the prior page. Finally, there is a new link added to the Resource page for the generic Consortium zenodo page. I like that we have added that. We are also discussing how to cite, https://github.com/CICE-Consortium/CICE/issues/465. I think we should think about how that page might fit into the "Version Index" and Resource page and how they are linked together.

eclare108213 commented 4 years ago

Release Table sounds good to me. I also like having the table - let's not get rid of it. There is a section in each of the RTDocs on how to cite the code. I think our revised wording should go there. I'm not sure it's mentioned or linked from anywhere, though, so that people would know to look for it there.

duvivier commented 4 years ago

I also really like the table and don't want to get rid of it. I'm fine with the title "Release Table" and use that wording throughout.

I'd be fine removing the release DOI stuff from the Resources page and just point at the Release Table and Zenodo community space.

We should probably provide information about how to cite the code that duplicates the RTD section or at least tells people to look there specifically. Mainly because I could imagine someone quickly wanting to cite the code or a release for a proposal or in a paper and not thinking to look at the documentation for the instructions how.

apcraig commented 4 years ago

I renamed the Icepack and CICE "Version Index" pages to "Release Table" and I have updated links on the READMEs and on the various wikis. It's possible I missed some links, so if you find a broken link, feel free to fix it or let me know and I can help sort it out.

duvivier commented 4 years ago

Looks great, thanks! I didn't see any broken links, but if any pop up we'll deal with them.

apcraig commented 4 years ago

I just did another sweep of the documentation to try to make the various links a little more consistent throughout. I also fixed a few links that were broken and cleaned up some others. In particular, I think we should use the following syntax as much as possible. The text associated with a link should match up with the name of the link. For instance,

[Resource Index](https://github.com/CICE-Consortium/About-Us/wiki/Resource-Index)

which would look like

Resource Index

and could appear in documents like

Consortium Resource Index CICE-Consortium Resource Index Resource Index page project Resource Index website

or similar. The point being that when we link to the Resource Index, we want the highlighted text to consistently be "Resource Index" throughout the document to help cue users to the fact that it's always the same document. For many documents, this should be straightforward. For the forum, I have used

[Forum](https://xenforo.cgd.ucar.edu/cesm/forums/cice-consortium.146/)

which looks like

Forum

Obviously, this approach will evolve as we move forward. We can always create exceptions or change document names or even relax the approach. It's possible there are still some broken links or links that are inconsistent in appearance or naming convention. Again, if anyone finds a problem, feel free to fix it or let me know.

phil-blain commented 4 years ago

. For the forum, I have used

[Forum](https://xenforo.cgd.ucar.edu/cesm/forums/cice-consortium.146/)

which looks like

Forum

I think @eclare108213 mentioned earlier that she preferred "Bulletin Board" ?

eclare108213 commented 4 years ago

Nope, I prefer "Forum"!

phil-blain commented 4 years ago

@eclare108213 sorry! :P I remembered backwards.

duvivier commented 4 years ago

@apcraig Do you think the "new" documentation scheme since July has been working? I don't have any issues with it on my end, nor have I heard any. I'm wondering if we should close the issue for now.

apcraig commented 4 years ago

Thanks @duvivier, I think the updated documentation is working fine and we improved a number of things. There is always more we can do.

I think the main outstanding issue is redundancy of the copyright and license. We don't yet have a process to maintain or manage the multiple instances. Maybe we can create a separate issue and close this one.