As a developer, I want to write a wiki for our users, using the VLab wiki as a starting point.

[HankHerr-NOAA]

We need a wiki for our user explaining how to obtain and run the software, how to declare an evaluation, and other aspects which are TBD. My plan is to start with a skeleton for an entry level page, then add the Declaration Language wiki from VLab one level down, with other wikis that are referred to migrated as well. I'll edit all wikis to make sure that they do not refer to NWC specific services or files. Once the Declaration Language wiki is migrated, we'll add other pages as appropriate.

I'm going to put the pages in the wiki, directly, but, eventually, we'll probably want to source control them. We can discuss that later.

Hank

[HankHerr-NOAA]

The page I'm going to use to translate from VLab Redmine textile format to GitHub markdown is here:

https://pandoc.org/try/

The from format is textile, and the to format is markdown_github. But, first, I need to create a top level minimal wiki.

Hank

[HankHerr-NOAA]

Turns out that the initial migration will point to the wiki pages from VLab. For example:

"Units of measurement"

I just need to find the VLab URLs, follow them, migrate the pointed to wiki, and then modify the VLab URLs appropriately.

Note that it appears the converting tool adds new lines inside of paragraphs enforcing a column-width limit on the text. However, when the wiki is viewed via browser, those new-lines are removed and the column width is controlled by the browser. If you want to see what I'm talking about, view the Declaration Language wiki, which I just created, and note the column width, then edit it and note that the column width is different.

[HankHerr-NOAA]

I'm about to convert the Units of Measurement wiki from VLab to GitHub. However, I need to add a task for later, but I don't see an ability to add a checklist item. Its probably because I'm overlooking it. The following task must be completed later:

Add the footer in the Units of Measurement VLab wiki to the new Units of Measurement GitHub wiki and figure out how to properly do super scripts.

I'm going to save the Units of Measurement wiki as I have it now and return to it later.

Hank

[HankHerr-NOAA]

There is a reference to a Google Drive document in the declaration language wiki:

The list of supported metrics is contained in this spreadsheet: list of metrics supported by WRES.

That will need to be open to the public or we'll need to move that to a wiki. Which is better?

[HankHerr-NOAA]

For the Units of Measurement task in bold, above, I can see the links defined in the wiki page when I edit it, but they do not show up in the text when viewed/previewed. However, the links do appear to be working. I'll have to investigate how to better handle those footnotes.

Hank

[HankHerr-NOAA]

I fixed the units of measurement links. They now appears as super scripts and there is a list at the bottom.

[HankHerr-NOAA]

The Declaration Language wiki and the wikis to which it links have been migrated to GitHub. It still needs a thorough proof read and link check to make sure I didn't make any mistakes. I'll start on that in a bit.

For the top level page, what do we want to include? The README covers the mechanics (I still need to proof read that), so should it just refer to that? What else needs to be mentioned in the wiki?

More later,

Hank

[HankHerr-NOAA]

There is probably more to do, but I'm going to put this out there for review before I spend too much more time on it:

https://github.com/NOAA-OWP/wres/wiki

Note that the software requirements section may not be accurate; please correct it as necessary. While Gradle may download the correct version of Java through the tool chain (iirc?), when using a production release .zip, the correct Java version must be present... at least that's what I need to do to run the script on a Linux VM.

If there are other wiki pages that should be translated over, please let me know. Currently, I've merely migrated those wikis to which the Declaration Language wiki refers. If I missed an important wiki, its because the Declaration Language wiki does not refer to it, or I just plain overlooked it.

I still need to do my own review, as well, so don't be surprised if there are some obvious mistakes. Thanks,

Hank

[epag]

I'm about to convert the Units of Measurement wiki from VLab to GitHub. However, I need to add a task for later, but I don't see an ability to add a checklist item. Its probably because I'm overlooking it. The following task must be completed later:

Tickets support markdown so you can add a tasklist

So you can edit the initial issue to contain a checklist

• [ ] You can also convert these into sub issues

[HankHerr-NOAA]

The tool I'm using (noted above) does not appear to handle code tags well. I just manually went through the Declaration Language wiki modifying the code tags to use the appropriate notation discussed in the meeting. I still have to modify the other wikis, but they aren't nearly as large.

[HankHerr-NOAA]

The other code tag were fixed. However, in the Units of Measurement, I did fix the superscripts to appear as super scripts, and the list of references at the bottom looks good, but the references to those super scripts do not. Specifically, I see this:

blah[¹]

I need to super script to just the number, not brackets around it, and I need it to link to the reference at the end. I'm not sure if that's possible.

There are other mistakes in the units of measurement wiki that I'm fixing now.

Hank

[HankHerr-NOAA]

Looks like the Unit of Measurement wiki was never updated to YAML. I'm going to try to do that after I check my emails,

Hank

[HankHerr-NOAA]

Done. There are still probably mistakes, but this is all I can do for now.

Hank

[HankHerr-NOAA]

@james-d-brown: Is the Declaration Language wiki supposed to define every declaration option at some point, even if its a brief mention in a table? I ask because resale_lenience is not currently described in that wiki, though it is mentioned in the time scale wiki which is linked.

Thanks,

Hank

P.S. We'll see if the '@' results in an email being sent to you.

[HankHerr-NOAA]

I'm going to go through the list of every wiki we offer in the VLab WRES User Support project. For each one, I'm going to check if its a reasonable candidate for migration to GitHub. My next comment will provide a list of those candidates.

Candidates will be rejected if its too NWC-centric or if its part of the Cookbook, which is GUI-centric.

Thanks,

Hank

[HankHerr-NOAA]

And... never mind. For now.

I realized that I did not properly migrate all of the wiki linked to from within the Declaration Language. There are at least a couple remaining that were referenced using [[...]] instead of URL:

Using covariates as filters Evaluation summary statistics

I want to migrate those, first. Having looked through the overall list of wikis, there are quite a few other candidates, as well, including a wiki on "Pooling geographic features" (which is surprisingly,to me, not referenced in Declaration Language), the CSV output format, format requirements for netCDF, and others. It might be best to just spend 15 minutes going through the list during a meeting and deciding which to migrate.

Let me do the two linked from within Declaration Language that I overlooked.

Hank

[HankHerr-NOAA]

I added a few more wikis and cleaned up the indentation of code examples in Declaration Language. One that I don't have time to do today is the examples wiki, Complete Examples of Evaluation Declarations. Thats referred to from within Section 18 of the declaration language wiki. I also want to double check how I'm linking to the other wikis, which currently involves treating it as any external URL, with the format being [display text](URL to link). I discovered shorthand for displaying images that uses double-brackets. Something similar probably exists for linking other pages within the same wiki.

Also, to add images, I had to clone the wiki repository, add the images to the repo, and then commit/push. Once I entered my username and password, it pushed fine. I found now way to upload images via the browser interface. What I'm not sure of is if the wiki, itself, is open to the public as with the main repository, and if branch protections apply. In other words, was I able to push without issue because I was one of the maintainers/admin? Or because the repository doesn't have branch protections requiring pull requests? If its the latter, does that mean anyone can push to the wiki repository?

Known tasks for next week:

• Clean up indentation for code examples in all wiki pages.
• Complete Examples of Evaluation Declaration wikis.
• Any other wikis directly or indirectly referenced from within the wikis I've already migrated.

More next week. Have a great weekend!

Hank

[HankHerr-NOAA]

I may not be able to pickup on the wiki changes until tomorrow, but I have question for now...

The tool I used appears to have enforced a column limit on the resulting wiki. When its presented to users, its not a problem; the new lines are seemingly ignored and the text fills up the browser window appropriately. However, when editing it, the column width limit kicks in and can make it appear a bit odd.

I'm on the fence as to what to do. If markdown is treated as code, then a column limit may be a good thing. After all, we have a column limit in our Java code, for example (not sure how strongly its enforced). But I'm not sure markdown should be treated as code, particularly if none of us are using an editor for the markdown where that would be an issue.

Anyone have any thoughts? Should I stick with column limited markdown or remove the excess newlines and relay on autowrapping in our editors?

Thanks,

Hank

[epag]

Do you have a page that I can look at that shows this as a good example? I think it would be better to accept this short coming rather than do everything manually at least

[HankHerr-NOAA]

You can see it in any of the wiki pages I created through migration from textile. For example: Declaration Language:

https://github.com/NOAA-OWP/wres/wiki/Declaration-Language

Just click Edit and you can see the column width limit applied.

Hank

[epag]

I think that looks fine personally, especially if the alternative is not using the tool or manually making changes

[HankHerr-NOAA]

The alternative would probably be me removing the excess new-lines by hand. Although it may be possible to script it in a reasonable way. The change would be made once per page, so it wouldn't be too torturous. I'm just wondering if, conceptually, if a column limit is sensible.

Hank

[james-d-brown]

If this is just a dev weakness, we can probably live with it. If it affects the product seen by users, probably not.

[HankHerr-NOAA]

I've seen no wiki impacted by the column width limit as of yet. I guess that means we can live with it. Just be ready when you go in to modify a wiki to see a column width that may be kind of ugly to work with.

I had said I should return to the wiki changes tomorrow, but I doubt that will happen. Probably won't be until Friday at this point. Repeating here the known tasks that remain to be done:

• Clean up indentation for code examples in all wiki pages.
• Complete Examples of Evaluation Declaration wikis.
• Any other wikis directly or indirectly referenced from within the wikis I've already migrated.

Hank