smartcontractkit / smartcontractkit/documentation

[Enhancement]: Fix the explanation of the V2 Job specs to be more instructive

Open
#778 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Chainlink Nodes enhancement
Dominant language
MDX
Stars
526
Forks
478
Avg merge
1d 9h
Merged PRs (30d)
75

Description

What would you like us to improve?

In this section: https://docs.chain.link/docs/jobs/#shared-fields

  • Reference to DAGs (Directed Acyclical Graphs) are computer science implementation details that may not be relevant to the user? If we are including them it needs to further their ability to quickly implement Jobs and not just educate them on the inner workings of job specs. At the very least they should be linked to the most clear, easily digestible link we can find to explain what they are but then we need to also explain why it matters that pipelines need to be acyclical, why the way they're processed by the Node makes them a directed graph vs undirected graph, etc etc. May not be immediately necessary nor useful for the target audience?
  • I am not familiar with DOT syntax, and perhaps we need to link to an easily consumable resource on what that is. If we link users to something like this we will quickly lose them in a rabbit hole and they are not likely to achieve their goal of getting a job up and running.
  • the explanation under observationSource also encourages the reader to see below on info on writing pipeline DAGs. Cannot see any obvious resource? If users google what chainlink Jobs are and land on this page, they would need more actionable information for quick outcomes, that do not add to cognitive load with new concepts and terms.
How important it is?

Very important if the objective of this page is to get a user to have a Job specified and added to their Node asap. The focus should be on what is necessary and sufficient to get them to that outcome, and eliminate "nice to haves".

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the V2 Job documentation's shared-fields section, especially the DAG, DOT syntax, and observationSource explanations. Review whether each concept helps users create and add a Job quickly; done means the guidance is actionable, links to clear resources where needed, and avoids unnecessary cognitive load.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.