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

Refactor docs #296

Open
wants to merge 13 commits into
base: main
Choose a base branch
from
Open

Refactor docs #296

wants to merge 13 commits into from

Conversation

natalieparellano
Copy link
Member

@natalieparellano natalieparellano commented Sep 21, 2023

Signed-off-by: Natalie Arellano <[email protected]>
Signed-off-by: Natalie Arellano <[email protected]>
Signed-off-by: Natalie Arellano <[email protected]>
@buildpack-bot
Copy link
Member

Maintainers,

As you review this RFC please queue up issues to be created using the following commands:

/queue-issue <repo> "<title>" [labels]...
/unqueue-issue <uid>

Issues

(none)

Signed-off-by: Natalie Arellano <[email protected]>
Copy link
Member

@AidanDelaney AidanDelaney left a comment

Choose a reason for hiding this comment

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

I like the general thrust of this proposal.

text/0000-re-org-docs.md Outdated Show resolved Hide resolved
text/0000-re-org-docs.md Outdated Show resolved Hide resolved
text/0000-re-org-docs.md Outdated Show resolved Hide resolved
text/0000-re-org-docs.md Outdated Show resolved Hide resolved
text/0000-re-org-docs.md Outdated Show resolved Hide resolved
text/0000-re-org-docs.md Outdated Show resolved Hide resolved
text/0000-re-org-docs.md Outdated Show resolved Hide resolved
Signed-off-by: Natalie Arellano <[email protected]>
Signed-off-by: Natalie Arellano <[email protected]>
@natalieparellano natalieparellano added type/rfc team/learning scope/team RFC scoped to a sub-team as opposed to the entire project. status/needs-steward labels Sep 27, 2023
Signed-off-by: Natalie Arellano <[email protected]>
Signed-off-by: Natalie Arellano <[email protected]>
@AidanDelaney
Copy link
Member

@natalieparellano Do you want to shepherd this, or would you prefer if I did it?

@natalieparellano
Copy link
Member Author

@AidanDelaney if you could that'd be great :)

@natalieparellano
Copy link
Member Author

@natalieparellano will update this RFC with some examples of what the sidebar could look like


- Define the target persona: all personas, including project contributors, can benefit from this.
- Explaining the feature largely in terms of examples.
- See the example [branch](https://github.com/buildpacks/docs/tree/refactor) of github.com/buildpacks/docs and abbreviated tree with notes below.
Copy link
Member Author

Choose a reason for hiding this comment

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

An example sidebar could look like:

Screenshot 2023-10-30 at 11 00 36 AM

Copy link
Member Author

Choose a reason for hiding this comment

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

Copy link
Member

Choose a reason for hiding this comment

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

I like this. It's much more straightforward than what I was thinking and thus more achievable.

Copy link
Member

@AidanDelaney AidanDelaney left a comment

Choose a reason for hiding this comment

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

LGTM :)

@natalieparellano
Copy link
Member Author

Moved to voting, closing Thurs Feb 8 :)


Why should we *not* do this?
- It's a lot of work
- Changing the structure of the docs could be surprising for users who are already familiar with its content
Copy link
Member

Choose a reason for hiding this comment

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

It also potentially breaks SEO and links to the documentation outside of us. Will we redirect to the homepage or other pages?

Land the RFC describing how to refactor our documentation
@natalieparellano
Copy link
Member Author

I'm not sure why this hasn't been merged (as it's already been implemented 🙃) - will take a look.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
scope/team RFC scoped to a sub-team as opposed to the entire project. team/learning type/rfc
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants