Writing Conventions for Markdown-based Docs
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 25/100
- Issue type
- Documentation
- Clarity
- Needs clarification
- Activity status
- Stale
- Tech stack
- markdown
- Domain
- documentation
Research direction
The issue names no repository files or tests. Start by reviewing the existing Markdown-based documentation and the linked O'Reilly convention references, then identify where project-wide writing guidance would belong. Done would require an agreed convention and a documented decision, but the issue does not define that outcome.
Written by the indexing model from the issue text.
Description
When writing a "how-to" (e.g: learn-xyz) or general project documentation, should we have a list of writing conventions the way O'Reilly books (the benchmark for tech books) always have a "Conventions Used in This Book" section at the start of the book e.g: http://www.oreilly.com/openbook/debian/book/prf1_02.html
Terminal Commands
When instructing people to run a certain command in the Terminal (Emulator), should we
- include the
$(dollar sign) in front of the command (or not) ?#discuss - explicitly state that the command has to be run in the terminal?
- use
constant width boldfor all "Commands or text to be typed by the user" ?
For a complete list of the O'Reilly Typography and Font Conventions
see: http://chimera.labs.oreilly.com/books/1230000000969/ch03.html
PDF Snapshot: O'Reilly-Typography-and-Font-Conventions.pdf
- Dominant language
- No language data
- Stars
- 92
- Forks
- 9
- PR merge metrics
- No merged PRs in 30d
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing 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.
More from dwyl/contributing
-
bug chore starter
Difficulty 1/5 Under an hour Newbie friendliness 38/100
dwyl/contributing#119 · 1 reaction ·
-
enhancement starter
Difficulty 1/5 1-3 hours Newbie friendliness 35/100
dwyl/contributing#118 · 1 reaction ·
-
discuss enhancement
Difficulty 4/5 3-5 days Newbie friendliness 25/100
dwyl/contributing#113 · 2 reactions ·
-
discuss enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 35/100
dwyl/contributing#112 · 1 reaction ·
-
Draft Pull Requests!Opendiscuss enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 42/100
dwyl/contributing#111 · 2 comments · 3 reactions ·
All issues in dwyl/contributing
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
cellrishi-code/claude-skills-atlas#165 ·
Maintainers usually reply within 1 day
-
documentation good first issue
Difficulty 1/5 1-3 hours Newbie friendliness 88/100
suradet-ps/codeframe#36 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 82/100
EchoTools/nevr-runtime#651 ·
Maintainers usually reply within 1 day
-
Docs: say where source and device come from in the Withings and Polar guidesPossibly taken A pull request linked to this issue is open or already merged. Openconnector docs good first issue
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
soma-intelligence/open-health-sync#134 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 1-3 hours Newbie friendliness 70/100
godotengine/godot-proposals#15663 ·