Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Configuration file pages as explanation and reference (Diátaxis) #10416

Merged
merged 10 commits into from
Jun 15, 2023

Conversation

benjaoming
Copy link
Contributor

@benjaoming benjaoming commented Jun 9, 2023

This PR proposes to:

  • Shorten Explanation top-level: In order to not make the Explanation top-level yet another item longer, we add the new subsection "Deep-dive into Read the Docs" (this which was already in the cards)
  • Change the general config-file/index to an explanation page (we could refactor the location, but in the special case of config-file contents, we currently have it all in this folder)
  • We drop the intermediate step config-file/index that's currently making users go through an unnecessary intermediate step

Might wanna add a note about the upcoming requirements to have a configuration file w/ a link to the blog post? Or do that later?

Fixes: #8648

Refs: #9747

This PR supersedes #9921


📚 Documentation previews 📚

Copy link
Member

@ericholscher ericholscher left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did some content updates here, I think we're close..

@benjaoming
Copy link
Contributor Author

@ericholscher what do you think about adding a small section about configuration files and implicit defaults, i.e. the topic of using latest for build images? I think this could be a good location to elaborate why it's not a supported feature. I'm thinking that having a reusable reference is valuable + consolidating knowledge from detailed discussions.

@ericholscher
Copy link
Member

@ericholscher what do you think about adding a small section about configuration files and implicit defaults, i.e. the topic of using latest for build images? I think this could be a good location to elaborate why it's not a supported feature. I'm thinking that having a reusable reference is valuable + consolidating knowledge from detailed discussions.

I think we can tackle that later. I don't want to expand the scope of this PR, so we cna can get it merged.

@benjaoming benjaoming merged commit a0651c5 into main Jun 15, 2023
@benjaoming benjaoming deleted the docs/configuration-reference-explanation branch June 15, 2023 11:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Archived in project
Development

Successfully merging this pull request may close these issues.

Make current config version more prominent in our docs
2 participants