Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create a glossary of terms for Parsl documentation #3426

Closed
3 of 5 tasks
WardLT opened this issue May 10, 2024 · 4 comments · Fixed by #3730
Closed
3 of 5 tasks

Create a glossary of terms for Parsl documentation #3426

WardLT opened this issue May 10, 2024 · 4 comments · Fixed by #3730

Comments

@WardLT
Copy link
Contributor

WardLT commented May 10, 2024

Is your feature request related to a problem? Please describe.
The many workflow systems vary in terminology they use, and Parsl is not special of this. We should create a Glossary for terms and make it prominent in the documentation for key concepts, such as:

  • Block
  • App
  • Job
  • Worker
  • Executor

Describe the solution you'd like
A documentation page with one sentence explanations for each term.

Describe alternatives you've considered
Linking people to the Quickstart, where I've tried to explain each term. However, the narrative form of that document is not great for quick reference.

Additional context
This would be great for our Outreachy team member :D

@benclifford
Copy link
Collaborator

cc @sophie-bui

@WardLT
Copy link
Contributor Author

WardLT commented May 10, 2024

Once we have the glossary, we should ensure consistency. I think we're good on using the same words, but I'm worried

@benclifford
Copy link
Collaborator

other concepts i've found poorly separated:

  • task
  • (worker) pool
  • manager (of workers)
  • app invocation - vs task, vs (definition of an) app

@benclifford
Copy link
Collaborator

  • node

... is a great one because it has two completely different meanings: node in the graph-theory sense of a piece of a DAG, if you have DAG-brain engaged; and something similar to what Internet Protocol people would call a host that executes code. for example, disambiguate this: a node is executed on a node.

  • resource

this gets loosely used in the same way that people use the word asset elsewhere - often to mean not much more than "thing".

github-merge-queue bot pushed a commit that referenced this issue Dec 29, 2024
# Description

Makes the style of the glossary section for the documentation match the
rest of the docs better.

- Only have it appear once in table of contents
- Remove bolding from section titles (Sphinx style already bolds them)
- Remove : from end of section title (to match other rst documents)
- Make underscores for titles match length (mismatch just bugs me)

# Changed Behaviour

N/A

# Fixes

Fixes #3426 (we've got the general prototype done)

## Type of change

- Update to human readable text: Documentation/error messages/comments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants