In looking at it again, the heading provides the context I'm after so that's great. I still think the readability would be improved if the file path of the example was included once at the start rather than with each heading.
A couple of other small points too, I think the guide would benefit (from a readability perspective) from a few style tweaks. The two that would help me the most would be increasing white space around code examples and making the margin above headings bigger than the margin below (the proximity principle). I've put together a very quick hack as a small example at http://scratchpad.pietschy.com/gradle/multi_project_builds.html Cheers Andrew 2009/5/6 Andrew Pietsch <[email protected]> > > The latest user guide (for Gradle 0.6) includes the name of the file, plus >> its location in the samples dir, in the title of each sample. For example >> have a look at the new multi-project builds chapter: >> >> http://gradle.org/userguide/latest/multi_project_builds.html >> >> (I'm not 100% happy with the format for the captions, but I think they are >> an improvement) >> >> Is this the sort of thing you were thinking of? >> > > That's much better but I'd prefer it to be just 'water/settings.gradle' > (i.e. without the leading 'userguide/multiproject/firstExample/'). When > I'm reading the documentation I'm really only interested in relative path of > the file (i.e. it's settings.gradle file in the project root); the full > path on every snippet obscures this. The actual location of the example is > useful, but I think it would be better stated once in a note at the > beginning of the example or something (e.g. 'For detailed examples please > see 'userguide/multiproject/firstExample'). > > Cheers > Andrew > > >
