I agree that if we have README that ships, that is the place for the pointer. And the changelog probably doesn’t need to ship either if we have a pointer in the README to the URL? https://solr.apache.org/docs/10_0_0/changes/Changes.html ?
I do like keeping our ref guide docs combined with Solr…. A strength is that because we this “monorepo” like setup, that code changes and Ref Guide changes stay together. Arguably, we should move things like documentation up to the root of the project.. ./solr/blah is often just an artifact of the time when Lucene and Solr shared a single repo. Eric > On Jul 4, 2026, at 7:05 PM, David Smiley <[email protected]> wrote: > > I'd like to propose removing the docs/ folder from the Solr binary > distribution and folding its useful content into README.txt instead. > > Background: docs/ in the binary distro comes from solr/documentation in > the source repo, and its content is published online for each release > already -- e.g. https://solr.apache.org/docs/10_0_0/ > <https://solr.apache.org/docs/10_0_0> for 10.0.0. > > Looking at what's actually in the folder today (10.0.0): > > docs/index.html -- a single HTML page whose only content is > two links: one to the online docs, one > to docs/changes/Changes.html > docs/solr.svg -- logo used by index.html > docs/changes/Changes.html -- an HTML-rendered changelog > docs/changes/*.css -- stylesheets for the above > > None of this is actually documentation -- it's a redirect page plus a > second, redundant copy of the changelog. We already ship CHANGELOG.md at > the top level of the distro, so docs/changes/ is pure duplication in a > different format. And README.txt already has a line pointing at > docs/index.html for "the online version of the Javadoc API documentation > and Tutorial" -- we can just replace that with the direct link and cut > out the middleman page entirely. > > Proposal: > - Stop bundling docs/ in the binary distribution. > - Add the online docs link (and the per-release changes link, if > desired) directly into README.txt's existing "Files included in an > Apache Solr binary distribution" section. > > This shrinks the distro slightly and removes a folder whose entire > purpose is now better served by a couple of README lines. > > You can see the current contents for yourself by downloading the 10.0.0 > slim distro and looking at docs/: > https://www.apache.org/dyn/closer.lua/solr/solr/10.0.0/solr-10.0.0-slim.tgz > <https://www.apache.org/dyn/closer.lua/solr/solr/10.0.0/solr-10.0.0-slim.tgz> > > Thoughts? > > Somewhat out of scope, but IMO the solr/documentation folder feels weird in > name/scope/purpose. Maybe renaming to site-docs to better reflect that the > destination/delivery is a website. I'm not sure if incorporating it into > the solr-site repo makes sense. > > ~ David Smiley > Apache Lucene/Solr Search Developer > http://www.linkedin.com/in/davidwsmiley > <http://www.linkedin.com/in/davidwsmiley> Disclaimer The information contained in this communication from the sender is confidential. It is intended solely for use by the recipient and others authorized to receive it. If you are not the recipient, you are hereby notified that any disclosure, copying, distribution or taking action in relation of the contents of this information is strictly prohibited and may be unlawful. This email has been scanned for viruses and malware, and may have been automatically archived by Mimecast, a leader in email security and cyber resilience. Mimecast integrates email defenses with brand protection, security awareness training, web security, compliance and other essential capabilities. Mimecast helps protect large and small organizations from malicious activity, human error and technology failure; and to lead the movement toward building a more resilient world. To find out more, visit our website.
