I have a question: What can be done if something in the documentation explains some basics for beginners fairly well, but is technically wrong/bad practice for advanced users/when using the configuration cache? Currently thinking of 2 examples: https://docs.gradle.org/current/userguide/writing_build_scripts.html#sec:local_variables -> this is not technically a local variable but an implicit property and these constructs break the configuration cache The other example is here: https://docs.gradle.org/current/userguide/writing_settings_files.html#settings_file_scripting Iterating over the list of directories in such a way will cause unnecessary configuration cache misses as clearing .gradle or build will invalidate the build cache and this needs to be done using a ValueSource These examples are both really great for beginners but really ugly when considering the configuration cache

Thank you for bringing it up! What I would normally do in this case is explicitly saying that it is a simple example to demonstrate the concept, and offer a link to another advanced solution in a proper location. Is also possible to just use code tabs to put multiple examples Cc @Laura Kassovic too :)

Thanks for the feedback. It's sometimes tough to explain basic concepts and using best practices at the same time. I will try to keep everything in mind for future doc development.