No homepage was: Useful documentation was: Truffle repository conversion

[Jaroslav Tulach]

On Tuesday 30 of June 2015 10:50:15 Stefan Marr wrote:
> 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

OK. Feel free to provide a patch. I can integrate it.

> 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/in
> dex-2301583.html

Yeah, the missing homepage URL is really a problem.

> Currently, none of the URLs answer all the questions above. OTN gets close,
> but only links to 

The OTN page is Oracle product page. It is edited by skilled editors, reviewed 
by marketing team, approved by VPs.  That is not the kind of homepage open 
source project needs.

We need a page which members of the community can instantly improve easily. 
E.g. probably wiki. We need a page with hints & hacks related to coding - e.g. 
no product/marketing stuff - for that one we could/should link to the OTN 
page.

> the Graal OpenJDK project, and from there, you won’t find
> Truffle at the moment, I think.

Right, there is just a small FAQ related to Truffle. Those of us who care 
about Truffle should expand the materials. I believe improving the existing 
OpenJDK wiki to have more Truffle related information is reasonable first 
step. We already have the space, so we don't need to ask for any permissions 
to fill it with useful content.

> A related practical matter, what would be the desired URL you guys would
> like to see on slides? 

Probably http://truffle.org? But having such top-level URL is kind of 
marketing decision and I am afraid it can take a while before such decision is 
made inside corporation like Oracle. Thus...

> 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.

...I would rather concentrate on creating good and useful content in README, 
Javadoc and wiki for now.
-jt