initial contributing.md #121
Conversation
There was a problem hiding this comment.
Hi @timothypratley, thanks, I added a few comments.
In general, I think if we'd like to help a new contributor, a more careful explanation is needed.
The statements here need to be clarified and need to be put in context in order to help a new contributor.
At the moment, making Clay contributor-friendly would be a more demanding task, and I am not sure about its priority given our limited resources.
I'm proposing we proceed as follows:
- If you find this page useful, we can merge it, but clarify that it is a WIP internal draft.
- Maybe the
preparesubset can become contributor-friendly after it is refactored intokindly-render. This might be a less-demanding task.
| It is recommended to discuss ideas in a topic thread under the [#clay-dev stream](https://clojurians.zulipchat.com/#narrow/stream/422115-clay-dev). | ||
|
|
||
| If you are interested in working on clay, | ||
| we'd love to help you get familiar with the code. |
There was a problem hiding this comment.
This statement is so kind and inviting. Indeed this is something we have been doing in practice with many Scicloj projects. However, I am not sure whether we have the capacity to promise that for the Clay project (maybe we should discuss this).
Maybe we can simply propose they reach out so we can chat about it?
https://scicloj.github.io/docs/community/contact/
| we'd love to help you get familiar with the code. | ||
| Maybe we can set up some pair programming sessions to help. | ||
|
|
||
| ## Building index.clj |
There was a problem hiding this comment.
This subsection title might be unclear.
Maybe "Building the documentation"?
| ## Concepts | ||
|
|
||
| Clay is built around the idea of a "context" (sometimes also called a "note"). | ||
| A context is a map that contains the original code, the form, and the evaluated value. |
There was a problem hiding this comment.
Actually the merged config is also part of the context.
| ## Concepts | ||
|
|
||
| Clay is built around the idea of a "context" (sometimes also called a "note"). | ||
| A context is a map that contains the original code, the form, and the evaluated value. |
There was a problem hiding this comment.
A more careful explanation is needed here.
We need to put things in context to clarify what we are talking about and what "the original code", etc. actually mean here.
| :kind :kind/hiccup} | ||
| ``` | ||
|
|
||
| `kindly-advice/advise` is responsible for generating the `:kind` part |
There was a problem hiding this comment.
Maybe clarify what library this is coming from.
|
|
||
| items: `[{:hiccup [:h1 "hello"] :dep []} {:md "# hello" :dep [:katex]}]` | ||
|
|
||
| We can always convert md->hiccup, hiccup->md if we have one of them and need the other one. |
There was a problem hiding this comment.
Need to clarify better what "We can always" means here.
What part of the workflow are we talking about?
When does it happen, etc.
|
|
||
| When we generate a Quarto document (.qmd), we prefer markdown. | ||
|
|
||
| Whe we directly generate HTML, we prefer hiccup. |
adds notes about development