hpc-intro icon indicating copy to clipboard operation
hpc-intro copied to clipboard

populate glossary

Open tkphd opened this issue 7 years ago • 14 comments

The glossary ~(reference.md)~ (guide.md) needs content. For a start:

tkphd avatar Sep 07 '18 16:09 tkphd

good idea and thanks for putting that into an issues. But always remember: Top priority for good teaching is reduction. There are many things in that list which I'd drop. I don't feel too polite to edit your issues directly. How about #38 ?

psteinb avatar Sep 10 '18 08:09 psteinb

Please feel free to edit the issue. I would prefer ~strikethrough~ tags over straight deletion. Discussion of what to include is more natural in an issue than in a PR.

For a start, Beowulf clusters are obsolete, grid and cloud computing are out of scope, GPGPU is to deep in the weeds...

tkphd avatar Sep 10 '18 16:09 tkphd

@tkphd I would say that grid and cloud computing are not out of scope -- I'd like to see this lessons adapted to use on a system like the Open Science Grid, which is not traditional HPC.

I have an alternative proposal for forming the glossary. How about going through the lessons and pulling out the terms that could use a definition?

ChristinaLK avatar Sep 10 '18 21:09 ChristinaLK

Good suggestion, @ChristinaLK. Perhaps a hybrid approach: go through the existing lessons, tagging or linking instances of jargon to the glossary, then reviewing what's undefined and what's never referenced? Not a trivial task...

tkphd avatar Sep 10 '18 22:09 tkphd

Yep. Reviewing the lessons seems like a manageable task and could be done piecemeal.

ChristinaLK avatar Sep 10 '18 22:09 ChristinaLK

It's all fine with me. Go ahead. I just fear that this repo will be restructured soon, so I suggest to hold your fingers for now.

psteinb avatar Sep 11 '18 13:09 psteinb

Good point. I'll focus on #40 and then come back to this.

ChristinaLK avatar Sep 11 '18 15:09 ChristinaLK

Reviewing this list, I'm honestly not sure the glossary is useful. When terms relevant to, and within scope for, the lessons come up, we define them. Anything that doesn't come up, is out-of-scope for us to define; a Web search is better suited than a glossary. Anything that does come up, but isn't adequately explained, we need to address within the lesson.

tkphd avatar Aug 07 '20 17:08 tkphd

Never noticed a glossary in the shell-novice reference page, but there it is. As a result, I don't think I'd abandon the glossary entirely, but it definitely shouldn't include terms we never use in the lessons (looks like the shell-novice glossary is keeping with that rule except maybe for "REPL"). Being able to point people at a single reference page including a review of terms seems useful, without them having to scroll through the entire lesson or hope for the best on a search. Not sure what else might go on a more complete reference page yet.

mikerenfro avatar Aug 08 '20 14:08 mikerenfro

some learners have asked for a glossary here and there during my HPC intro courses.

some automation would be helpful here I believe, so that if we define a term during a lesson, it is automagically appended to the glossary.

psteinb avatar Aug 31 '20 07:08 psteinb

I would like to vote to keep glossaries. We can choose to link to the glossaries page with anchors from individual lesson materials.

annajiat avatar Aug 31 '20 07:08 annajiat

May be helpful to have this, but could be in extra materials as done for shell-lesson

bkmgit avatar Jan 28 '21 16:01 bkmgit

It already is: Extras -> Reference.

tkphd avatar Jan 28 '21 16:01 tkphd

The glossary is no longer in reference.md, it's now in _extras/guide.md. Edited the leading comment on this issue to reflect the new location.

reid-a avatar Jun 03 '21 12:06 reid-a