No strong preference on my side, but I found this project of Lauri Apple very useful:
https://github.com/LappleApple/feedmereadmes You can ask for input on your README file there (they may send a PR for updating it) and it also contains a "README maturity model". Perhaps it's helpful for you, too. --Gunnar 2018-06-04 14:32 GMT+02:00 Sanne Grinovero <sa...@hibernate.org>: > The historical objection has been that many users get the zip of our > project on a floppy disk and have no access to the internet. > > That might be an obsolete statement nowadays? They'll use a > USB stick today ;) > > Still, we know that e.g. people in China and similar places can't > always access our online resources, even if they "have internet". > University assignments/labs might have similar limitations even in Europe. > > I have no strong objections, do it if you feel strongly about this > "inconsistency". > > Personally, it hasn't bothered me much to occasionally have to update > the README, and I don't think people will expect that a zip they keep > in a drawer will be the better source of information if they happen to > have access to hibernate.org > > Cheers, > Sanne > > > > On 4 June 2018 at 12:51, Yoann Rodiere <yo...@hibernate.org> wrote: > > Hi everyone, > > > > TL;DR: I would like to strip down the README in Hibernate Search to > > redirect users to the website, which is better suited for presenting > > available versions, and helping users to get started. See what I mean in > this > > PR <https://github.com/hibernate/hibernate-search/pull/1692>. Any > > objections? > > > > Currently, the README.md in NoORM projects duplicates a bit of > information > > from our website and documentation: > > > > - The version number and date of the latest release: > > https://github.com/hibernate/hibernate-search#hibernate-search vs. > > http://hibernate.org/search/releases/ > > - A description of the project: > > https://github.com/hibernate/hibernate-search#description vs. > > http://hibernate.org/search/ > > - The requirements: > > https://github.com/hibernate/hibernate-search#requirements vs. > > http://hibernate.org/search/releases/#compatibility-matrix or > > http://hibernate.org/search/releases/5.10/#compatibility > > - Installation instructions: > > https://github.com/hibernate/hibernate-search#maven + > > https://github.com/hibernate/hibernate-search#sourceforge-bundle vs. > > http://hibernate.org/search/releases/5.10/#get-it or > > http://hibernate.org/search/documentation/getting-started/ > > > > > > Some of this information is updated manually when we don'r forget about > it, > > and some of it (the latest release) is updated automatically when we > > perform a release on master. > > > > As a result, from time to time the information is not in sync. Right now, > > in Search, the version displayed in the README is 5.10.0.Final, whereas > the > > latest release is 5.10.1.Final and the master branch hosts the > > 5.11.0-SNAPSHOT code. This is because the release scripts do not update > > master when we release from another branch, and we have to do it manually > > (that's expected: doing otherwise would be too complex). > > > > Also, the information is partial: > > > > - the README currently completely hides the fact that other Hibernate > > Search versions are still maintained and can work well with older > versions > > of Hibernate ORM. > > - whenever the latest release is an alpha/beta/CR, we usually display > > installation instructions for the latest development version, and > > completely hide information about the latest stable version. > > > > What's worse, keeping the documentation on branch master the README on > > branch master may prove confusing: the README refers to the latest > release, > > but the rest of the code may have been updated since the latest release, > > sometimes significantly so. We will have trouble dealing with this when > we > > merge Hibernate Search 6, in particular. > > > > We may not agree on what is the best solution, but let's at least agree > > this is not ideal, especially when it comes to informing users about the > > stable version they want to use. > > > > We could put in more effort, try our very best to keep everything in sync > > and as complete as possible/necessary. Add more documentation about the > > release process. Try our best to do less mistakes. We could. But > obviously, > > nobody is perfect, and so never will this README. > > > > Other projects, such as Spring Boot ( > > https://github.com/spring-projects/spring-boot) or, more relevantly, > > Hibernate ORM (https://github.com/hwithibernate/hibernate-orm > > <https://github.com/hibernate/hibernate-orm>), simply do not refer to > the > > latest version in their README, and redirect to their website for all > > version-specific information. The README focuses on presenting the > project, > > redirecting users to the website, and giving contributor-friendly > > information. > > > > I find this solution both elegant and powerful. Presenting the project is > > always necessary, but guiding users to the right version and giving > getting > > started instructions is something complex, and something we already do on > > our website. So why not redirect people there? All links stay valid and > > relevant as long as the website is up and kept updated, and the impact of > > maintainers forgetting to update the README is far smaller. One less > thing > > to worry about for maintainers, and better guidance for prospective > users. > > > > A simple link to the getting started guide could be enough for most > users, > > but we can go a step further and offer additional links. I just sent a > pull > > request to show how I see it implemented in Search; please let me know > what > > you think. > > The PR: https://github.com/hibernate/hibernate-search/pull/1692 > > Preview of the README as seen from the GitHub web view: > > https://github.com/yrodiere/hibernate-search/blob/ > ae4d347fa4c647a3c5ddb6f43412cf3dce0e354e/README.md > > > > Cheers, > > -- > > Yoann Rodiere > > yo...@hibernate.org / yrodi...@redhat.com > > Software Engineer > > Hibernate NoORM team > > _______________________________________________ > > hibernate-dev mailing list > > hibernate-dev@lists.jboss.org > > https://lists.jboss.org/mailman/listinfo/hibernate-dev > _______________________________________________ > hibernate-dev mailing list > hibernate-dev@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev > _______________________________________________ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev