Useful documentation was: Truffle repository conversion

[Stefan Marr]

Hi Jaroslav:

> On 30 Jun 2015, at 09:18, Jaroslav Tulach <jaroslav.tulach at oracle.com> 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.

See
http://lafo.ssw.uni-linz.ac.at/hg/truffle/file/4858c5e074e9/README.md

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: http://ssw.jku.at/Research/Projects/JVM/Truffle.html
as well as the FAQ: https://wiki.openjdk.java.net/display/Graal/Truffle+FAQ+and+Guidelines
And perhaps the OTN one: http://www.oracle.com/technetwork/oracle-labs/program-languages/overview/index-2301583.html

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


-- 
Stefan Marr
Johannes Kepler Universität Linz
http://stefan-marr.de/research/