Break documentation style guide out into its own file #9813
Conversation
This is the start of a larger style guide that we should have, trying to capture places where we make decisions.
ericholscher
changed the title
ericholscher
requested review from
benjaoming
and removed request for
agjohnson
…átaxis) (#9675) * Re-label VCS integration as a how-to guide and let's call it "Git platform integration"? * Revert back to saying VCS (to cut short discussion) * Revert another change, just to reduce distractions * WIP: Splitting up and updating VCS integration * Update references to integrations after the split * Remove the generic framing of VCS providers * Add git integrations to the list of explanations * Add a local table of content, move oddly placed instructions, fixup broken headline levels * Remove local TOC, move individual provider guides to tabs * Makes it possible to open up a tab using a sphinx label reference * Move Debugging Webhooks into Troubleshooting * Remove section Resyncing webhooks * Comment about scope * Update docs/user/integrations.rst Co-authored-by: Eric Holscher <[email protected]> * WIP * Adds a draft of explanation of how continuous documentation fits into the landscape * Apply suggestions from code review @ericholscher Co-authored-by: Eric Holscher <[email protected]> * Update docs/user/integrations.rst * Add explanation about versioning and a seealso for Automation Rules * Tweak the Automated Versioning subsection and add a seealso for the flyout menu * Refinements to versioning subsection * Update docs/user/integrations.rst Co-authored-by: Eric Holscher <[email protected]> * Remove paragraph that already had a broken reference (even before AFAICT) and that does not lead to clear solutions * Make Git a proper noun. This way of writing "Git repository" etc. is widely used, example: https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository. Ref #9813 Co-authored-by: Eric Holscher <[email protected]>
Co-authored-by: Benjamin Balder Bach <[email protected]>
Co-authored-by: Benjamin Balder Bach <[email protected]>
|
Addressed feedback 👍 |
There was a problem hiding this comment.
I think this PR worked really well. We went over several writing style preferences which may have seemed too small for processing in isolation. But by combining it in one PR, we got several things dealt with at once and the whole team's attention was there as well.
Seems like all the feedback is addressed. We could open a follow-up issue for "capturing" small items for the next "round of style guide updates"?
I don't immediately recall anything else "ripe" for the styleguide, but I think there are several conventions that are coming from our Diátaxis work that we can address once we feel that it has settled in:
- How we give titles: How-tos, explanations etc.
- Introduction paragraphs
seealso::usage- How we use Diátaxis (a super-quick instruction list to new authors)
|
@benjaoming Yea, my hope here is to slowly add things here as we discuss them, instead of queueing them up. I think the
Yea, we should likely port our checklist here as well (https://docs.google.com/document/d/1Ir8UvupznvAH4oF4-DEiXrILnEk2Lqsg4FrPDA-8uXA/edit#) in another PR. |
|
@ericholscher I really enjoyed how you combined several additions in one PR, I think it's a great service to team collaboration, rather than for instance making 1 PR to say "lets write Git instead of git" and have that whole process separately. We saved a lot of time 💯 |
|
Yea, if we have a bunch of changes that are similar, they should be in the same PR. Otherwise it just gets messy. |
This is the start of a larger style guide that we should have,
trying to capture places where we make decisions.
Lots of inspiration possible here: https://docs.pylonsproject.org/projects/docs-style-guide/
Closes readthedocs/meta#65
📚 Documentation previews 📚
docs): https://docs--9813.org.readthedocs.build/en/9813/dev): https://dev--9813.org.readthedocs.build/en/9813/