pymc-devs / pymc-devs/pymc-examples
Guidance on writing: person, passive/active voice...
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 398
- Forks
- 325
- Avg merge
- 9d 15m
- Merged PRs (30d)
- 1
Description
Is there a preferred way to address users? Especially for tutorials where we want to give instructions to the reader. Guidance on commenting and explaining code: explanation in markdown above the code cell? below? general explanation in markdown only and implementation details as comments within the code? glossary terms, how do we know if a term should be explained in the notebook or in the gossary, or in both even. other potentially controversial topics?
cc @martinacantaro
It doesn't need to be very extensive and it can even be mostly links to other pages, but I think it will make both writing and reviewing notebooks easier
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the repository's Jupyter notebooks and their Markdown guidance to identify existing conventions for addressing readers, voice, code explanations, and glossary terms. Draft concise guidance or links covering these questions, then verify that it would help both notebook authors and reviewers.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- jupyter-notebook, markdown, python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 32/100