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

Add note to divert away from adding content to user guide #11323

Conversation

pradyunsg
Copy link
Member

This guide is being broken up, and multiple folks have now tried to add content to it instead of adding dedicated pages for it.

This note should help direct contributors away from adding more content on this page, to stop the bleeding and avoid regressing on the amount of content we'll have to move out of this page later.

Related to #9475, in that it is meant to stop the bleeding since we're adding new contents to the pages that we're also trying to remove content from. :)

This guide is being broken up, and multiple folks have now tried to add
content to it instead of adding dedicated pages for it.

This note should help direct contributors away from adding more content
on this page, to stop the bleeding and avoid regressing on the amount of
content we'll have to move out of this page later.
@pradyunsg pradyunsg added type: docs Documentation related skip news Does not need a NEWS file entry (eg: trivial changes) labels Jul 29, 2022
@pfmoore
Copy link
Member

pfmoore commented Jul 29, 2022

+1 on the idea, but as a point of information, there's at best a 50-50 chance I'd have read that text when trying to add something.

I got to the user guide by reading the rendered content on https://pip.pypa.io, and deciding that my content fitted here, because it wasn't big enough to warrant a "topic", and it was more "guide" than "reference". Then, I opened the user-guide.rst file. As I use VS Code, if I'd been in that file before there's a good chance it would have dropped me back where I'd previously had it open, and I may never even have seen the block at the top.

The other point is that even having seen this, "consider if this content can live on its own" would have led me to think "it's not really substantial enough to warrant a whole page to itself, so it's better in a single page full of shorter sections".

@pradyunsg
Copy link
Member Author

Yea, it's fine to miss out on a few cases like that -- the metric for what gets added is subjective anyway and, if someone doesn't have a look at it, it's not like anyone's gonna scold them for not looking.

This is mainly to make our lives easier, by giving us a clearer place to point to about "hey, we're actively doing a thing and this works against that -- see {note} for details". :)

@pradyunsg pradyunsg merged commit 0755d5c into pypa:main Jul 29, 2022
@pradyunsg pradyunsg deleted the add-notes-to-divert-adding-new-docs-content-on-long-pages branch July 29, 2022 15:55
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Aug 14, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
skip news Does not need a NEWS file entry (eg: trivial changes) type: docs Documentation related
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants