Docs: New Explanation sub-levels + high-level introduction as explanation (Diátaxis) #10071
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
I got motivated to write this, but struggled to figure out what to say in a clear way.. Leaving this in a draft for another day.
…rg into diataxis/explanation-refactor
benjaoming
changed the title
benjaoming
added
Improvement
…re precise concept
…hould probably remove old content
…tentially a diagram)
…ataxis/explanation-refactor
…/readthedocs.org into diataxis/explanation-refactor
31 tasks
…ataxis/explanation-refactor
…g sections. Some work still left.
|
@ericholscher this is now ready for review, of course I have left unintentional mistakes and there are many things that can benefit from your direct inputs. Please feel free to push directly 💯 Also see my updated description at the top ⬆️ |
|
Btw... since there's a lot of new content, maybe the best way to start reviewing it is to build it locally since the PR preview has a lot of disturbing "diff view" :) |
benjaoming
changed the title
There was a problem hiding this comment.
Overall this is a great change, but I worry that we're confusing the value we're providing to the user in terms of explanation, and not actually documenting how things work at a technical level, which is something the old docs did well around integrations that seem to be lost.
There's still a bunch more work here, it's a bit overwhelming to try and get all the examples to fit together, and I'm running out of energy to do a whole refactor.
…ataxis/explanation-refactor
2 tasks
benjaoming
added a commit
to benjaoming/readthedocs.org
that referenced
this pull request
Apr 18, 2023
2 tasks
…ataxis/explanation-refactor
…/readthedocs.org into diataxis/explanation-refactor
benjaoming
added a commit
that referenced
this pull request
Apr 19, 2023
* Adds "reproducible" to glossary * Adds glossary entries from #10071 * Make "webhook" respect a-z * Improve reproducible entry * Simplify the definition so its easier to understand * Move root URL so it's a-z * Remove "profile page" * Add "pinning" to glossary * Apply suggestions from @stsewd and @humitos code review Co-authored-by: Manuel Kaufmann <[email protected]> Co-authored-by: Santos Gallegos <[email protected]> * Update docs/user/glossary.rst Co-authored-by: Manuel Kaufmann <[email protected]> * Put defining sentence first * Add some references to new glossary entries * Put definition first * Add more references to pinning --------- Co-authored-by: Manuel Kaufmann <[email protected]> Co-authored-by: Santos Gallegos <[email protected]>
…ataxis/explanation-refactor
…ataxis/explanation-refactor
…/readthedocs.org into diataxis/explanation-refactor
…ataxis/explanation-refactor
…ataxis/explanation-refactor
…ataxis/explanation-refactor
|
Going to close this, and pull the small changes into a future PR. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Reviewing, cc: @ericholscher
The main main main contribution here is to organize the explanation section and add a very important main introduction, "Choosing a dedicated documentation platform".
Currently, this will have a lot of text that can be shortened or clarified.
You might also want to add something, but please see the comments at the top of "Choosing a dedicated documentation platform"
A lot of intentions are left behind as reST comments.. they can be eliminated by simply choosing to "not do this" and delete the comment.
Supersedes https://github.com/readthedocs/readthedocs.org/pull/10063/files with the full context of a new Explanation section.
Some filenames are now so badly misleading that they should be changed.
Possibly, add a graphic for "Continuous Documentation" to replace the lengthy Webhook explanationjust remove that explanation for now📚 Documentation previews 📚
docs): https://docs--10071.org.readthedocs.build/en/10071/dev): https://dev--10071.org.readthedocs.build/en/10071/