> > One observation though: there are some docs under the help folder (that > too as text files) and some under dev-docs. I personally feel all these > should be organized into the dev-docs folder (as .md files for readability > on github and IDEs), since that was the first place I went to look for any > docs. >
Expectations are different depending on whom you ask. I prefer those txt files over md files, actually - they're easier to cat to terminal/grep, etc. And there is a gradle task that shows them - type: gradlew help and you'll see what I mean: This is Lucene's gradle build. See some guidelines, ant-equivalent commands etc. under help/*; or type: gradlew :helpWorkflow # Typical workflow commands. gradlew :helpTests # Tests, filtering, beasting, etc. gradlew :helpFormatting # Code formatting conventions. gradlew :helpJvms # Using alternative or EA JVM toolchains. gradlew :helpDeps # Declaring, inspecting and excluding dependencies. gradlew :helpForbiddenApis # How to add/apply rules for forbidden APIs. gradlew :helpLocalSettings # Local settings, overrides and build performance tweaks. gradlew :helpRegeneration # How to refresh generated and derived resources. gradlew :helpJmh # JMH micro-benchmarks. gradlew :helpGit # Git assistance and guides. gradlew :helpIDEs # IDE support. gradlew :helpPublishing # Maven and other artifact publishing, signing, etc. The "dev-docs" are mostly concerned with processes and procedures; the help/ is, I think, more focused on development/code. But you're entitled to your own opinion, of course. ;) Dawid
