readthedocs / readthedocs/addons

Better addons documentation

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

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
48
Forks
29
Avg merge
3d 18h
Merged PRs (30d)
6

Description

Right now we have a documentation project in this repository which is just release and testing information for core team. This doesn't seem super useful to maintain as a project and the content feels misplaced.

Operations information should be in our ops playbook docs and testing/development info doesn't really require a whole documentation project. This could be in the readme or our development playbook docs, but the content in the readme here is mostly replicating the marketing content that we're maintaining in our application docs.

The documentation our users need from us is instead deeper information on our API, events triggered, and CSS customization. We have some examples and a basic list at:

https://docs.readthedocs.com/platform/stable/addons.html

But it is cumbersome and disconnected to have to document this level of detail in another repository. Especially because we benefit on the development side from documentation in source files.

What I'm describing is:

  • Move operations documentation for core team to our operations playbook docs
  • Keep the readme just information needed to work with the repository
  • Move/keep marketing content in our application documentation and website for now -- screenshots/etc
  • Thoroughly document the library API, events, and CSS customization here. Use Sphinx (and probably JSDoc and autoanysrc for CSS) to document at the source files.
  • Use this project as a subproject on our main docs project, https://docs.readthedocs.com/addons/

Contributor guide

No contributing guide indexed for this repository

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 by reviewing the existing addons documentation linked in the issue, the repository README, and the source files containing API, event, and CSS customization details. Done means operations and marketing material have clear destinations, the README is repository-focused, and user-facing API, event, and CSS documentation is integrated into the main docs project.

Written by the indexing model from the issue text.

Assessment

Tech stack
css, javascript
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.