On 8/12/09 4:24 AM, Hans Dockter wrote:
Cedric had some issues with out mailing list, so I'm posting this on
his behalf:
------------------
Hello Gradle users,
As some of you know, I recently tried to convert my build
(http://testng.org) to Gradle but I didn't make much progress after a
few hours, despite reading all the docs and mailing-list messages I
could find, so I thought I'd share my experience here.
First of all, I have to say that I'm very impressed with the effort
that went into the user guide. The doc looks very professional and
thorough, and I especially like the "one big web page" format (I did
the exact same thing with TestNG and users absolutely love the fact
they can do a search in the entire documentation so quickly or that
they can print it and take it home with them).
Having said that, I think this particular document is not a good
introduction for a couple of reasons:
* It doesn't emphasize migration. I'm guessing most people who
will come across this document will want to convert an existing build
(most likely ant and sometimes Maven) to Gradle. This should be the
first chapter.
* It's not high level enough. I've read the whole document maybe
one and half times now and I'm still not sure what the concepts and
building blocks are, what the difference between a module an a
dependency is, what names are reserved, which ones are examples, etc...
What's a good option for structuring this? I can think of a few
possibilities:
1. A single chapter early in the user guide which briefly defines each
concept, maybe with some examples.
2. A section at the start of each tutorial chapter which defines the
concepts that the chapter is going to cover.
3. Include the definition into the tutorial section which introduces the
concept.
4. A glossary and index at the end of the user guide.
We probably want to use a couple of these options. I think option 2 is a
good place to start.
A lot of the high-level material is actually there in the user guide.
It's just hard to find in the 200+ pages, and is inconsistently
structured. We could relatively easily re-arrange the existing content
to make things easier to find.
Perhaps a first pass could simply be to separate the existing chapters
into their various types:
1. start with early beginner tutorial chapters ('getting started',
'build script basics', 'java quickstart')
2. then special interest topics chapters ('more about tasks', 'logging',
'writing custom tasks', 'using ant')
3. then reference chapters ('the java plugin', 'Gradle command-line')
Some existing chapters would need splitting, I think (eg 'multi-project
builds', 'dependency management') or merging into other chapters (eg
'this and that').
Then, we can review each beginner tutorial, and add in empty or
placeholder sections for the missing stuff: missing concepts, and
missing high-level material for the concepts. I think even a section
with just a heading or a single sentence adds some value. And by
applying a consistent structure, it will become apparent what high-level
material is missing, and also provide a template for new material as we
add it.
I don't want to migrate my build by doing copy/pastes that I don't
understand, because this guarantees that in a few months from now, I
still won't understand how my build works, much less how to modify
it. I will only switch to a new build system if I can completely
understand how it works, philosophically and technically.
I absolutely agree. We want people to understand what's going on in the
build script, rather than just copying magic incantations they find via
google. It leads to a much better user experience, and is just less
frustrating for everyone.
TestNG's build is pretty straightforward (although interestingly,
Maven can't achieve it, I can go into details if you're curious) and
the two things that I needed to get started are:
* How do I change the default source directories?
* How do I configure my classpath to point to local jar files?
I ended up reading about variables called srcDirNames or something
such, none of which are mentioned in that doc anywhere. I still
wasn't able to get these variables to work properly, by the way, so
I'm still in the dark as to how to do this. And I still don't know
how to add local jar files to my compile and runtime classpath. I'm
guessing this involves specifying artifacts with some file:/// tricks
or something like that, but I couldn't find any example anywhere (not
just in your doc, I really mean anywhere in my web searches).
My ant build has been working flawlessly for years and I'm very happy
with it but I'm also always trying to streamline things and I think
Gradle has the power to trim down my build files considerably, so I'd
really like to get this working and see if I would be happy with the
final result.
Thanks for reading :-)
Thanks for the feedback. I think we can sort out the documentation so
other people don't suffer the same frustrations.
--
Adam Murdoch
Gradle Developer
http://www.gradle.org
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
