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] Reorganize content in README.md #5437

Closed
stevepiercy opened this issue Nov 24, 2023 · 2 comments · Fixed by #5511
Closed

[docs] Reorganize content in README.md #5437

stevepiercy opened this issue Nov 24, 2023 · 2 comments · Fixed by #5511

Comments

@stevepiercy
Copy link
Collaborator

There is marketing content in the README.md. READMEs should focus on the developer. As it is, a reader must scroll down to the end of the README to learn how to contribute. Additionally some of the content belongs in the Documentation which would reduce maintenance and redundancy. I would suggest the following reorganization.

Volto

No change.

Introduction

No change.

Demo

No change.

Create a Volto project

No change.

Contributing to Volto

Rename to "Contributing".

Add a sentence.

For newcomers to Volto, Plone, or open source software, you must read and follow [First-time contributors](https://6.docs.plone.org/contributing/first-time.html).

Documentation

No change.

Supported Plone and Python versions

Move to https://6.docs.plone.org/volto/contributing/version-policy.html#plone-and-plone-rest-api, merge content in destination, and provide a link to its new location.

Also include this sentence:

See the [Plone Release Schedule](https://plone.org/download/release-schedule) for details of maintenance and support.

Supported Node.js versions

Move content to https://6.docs.plone.org/volto/contributing/version-policy.html#node-js, and provide a link to its new location.

Supported browsers

Move to just after https://6.docs.plone.org/volto/contributing/version-policy.html#node-js, and provide a link to its new location.

Known good set of versions for backend packages

Move to https://6.docs.plone.org/volto/contributing/version-policy.html#plone-and-plone-rest-api, merge content in destination. Remove heading, no reference link.

Volto in Production

Move content to Volto Awesome. Merge content into https://github.com/collective/awesome-volto#open-source-websites-built-with-volto, avoid duplication, and create a new section "Other websites built with Volto" for the non-open source websites.

Contributors

No change.

License

No change.

@fredvd
Copy link
Sponsor Member

fredvd commented Dec 5, 2023

There is marketing content in the README.md. READMEs should focus on the developer.

The main reason there is 'marketing' and generic information in this readme, as is in the README 's of Plone/ Products.CMFlone and volto repo is that it is also used to generate the homepage page on package repositories like pypi or in this case npmjs.com: https://www.npmjs.com/package/@plone/volto

These sites are indexed and have reach and visibility from people searching for packages. And it is not only developers who see/find those homepages.

@stevepiercy
Copy link
Collaborator Author

The content headings would still exist, and most sections would not be changed. For the content that would be moved, the authoritative sources of the material would be better maintained, instead of fractured and inconsistent across multiple locations. Normally I would agree with Marketing All The Things™, but I think the maintenance burden outweighs the negligible benefit of preserving content on npmjs.com, based on Matomo stats of referrals from npmjs.com (roughly 0.08% of total referrals).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: Done
Development

Successfully merging a pull request may close this issue.

4 participants