Agreed this is great and difficult work, Ilan. Thanks so much for taking it on.
I wonder if some of this maybe should end up in Javadocs? If those classes don’t say what they’re doing or seem incomplete (and I have no idea what they say about themselves) then we should consider maybe using some of this to improve that? I don’t have much to say about the content - I might understand this all better if I read a doc like this though! - except to reply to David’s question to me: On Apr 23, 2020, 2:36 PM -0500, David Smiley <dsmi...@apache.org>, wrote: <snip> > > This is "developer documentation". Cassandra: I see you created > solr/dev-docs/ and I suppose this would best belong there? Mark Miller had > tried Confluence. Pros/cons there. I want to ensure readers of the code in > Overseer (and maybe other key class or two) notice this dev documentation. > Should I add a http link to the GitHub location of the dev doc markdown, or > do you recommend something else? > Well, I added the directories but I didn’t just make it up - we had a thread in the Dev list about doing it and since no one else moved to make it happen and I had some internal docs to write when I handed off PMC chair to Anshum, I did it. But besides being what we already said we wanted to do, I think it should go in our source code for at least all the same reasons we put the Ref Guide in the source - that’s where we already are, that’s where contributors need to be, and we can ensure the docs are properly relevant to the versions via our branching approach. I have a Google Docs add-on which can convert Google docs to Asciidoc format, which for a document this complex I would recommend as a format. The add-on is not going to do this doc perfectly, but will get 50% or more the way there. I’d be willing to give it a try, but if people want a mix of Asciidoc + Markdown formatted files and want to convert this to Markdown, by all means go for it.
