Useful documentation was: Truffle repository conversion

Stefan Marr java at
Tue Jun 30 08:50:15 UTC 2015

Hi Jaroslav:

> On 30 Jun 2015, at 09:18, Jaroslav Tulach <jaroslav.tulach at> wrote:
> On Monday, June 29, 2015 08:32:54 PM Stefan Marr wrote:
>> I could lend a hand with that.
> That would be more than welcomed. A fix to API documentation is at least as 
> important as fix to the actual code.

At the moment, I was just thinking about the README.


Might be valid for Graal and for Truffle, but more specifically for the Truffle repo, because that one is the one I am interested in from a language’s research/implementer perspective.

When I try to think of what I want from a repo README, then the following would be useful:

- brief intro what it is
- instructions how to build and use it (only the basics)
- pointers to further resources such as
   - a link to the main/official website
   - documentation, tutorials, or if that’s absent links to projects using it
   - where to find the community, and a note on how to interact/contribute
- license information

When pointing people to Truffle, I am always a little torn what a good entry point is.
Currently we got the SSW site:
as well as the FAQ:
And perhaps the OTN one:

Currently, none of the URLs answer all the questions above. OTN gets close, but only links to the Graal OpenJDK project, and from there, you won’t find Truffle at the moment, I think.

A related practical matter, what would be the desired URL you guys would like to see on slides?
Would be nice if there could be a high-level ‘Hello, Welcome, This is What I am’ kind of page or README I could use for the slides for the Truffle workshop.

Best regards

Stefan Marr
Johannes Kepler Universität Linz

More information about the graal-dev mailing list