Re: [go-nuts] golang playground for spec examples, article examples, docs examples

[Ian Lance Taylor]

On Wed, Feb 13, 2013 at 4:54 AM, <itmi...@gmail.com> wrote:
>
> There are a number of examples in the spec.
> For the local version of the spec, it makes sense to have the examples
> "hardcoded" in the page.
> For the online version, using golang playground for examples, would that
> potentially be a future problem, for the spec or for any kind of docs,
> articles etcetera?

The examples in the spec are not complete programs, and making them
into complete programs would add unnecessary padding. So I'm not sure
it's a good idea there.

For other docs, like Effective Go, it could be done. If you look at
the Effective Go source, you will see that it uses {{code}} links to
bring in programs. We could perhaps modify godoc to link to the
playground for those if think it would be useful.

Ian

[Kyle Lemons]

On Wed, Feb 13, 2013 at 6:46 AM, Ian Lance Taylor <ia...@google.com> wrote:

On Wed, Feb 13, 2013 at 4:54 AM,  <itmi...@gmail.com> wrote:
>
> There are a number of examples in the spec.
> For the local version of the spec, it makes sense to have the examples
> "hardcoded" in the page.
> For the online version, using golang playground for examples, would that
> potentially be a future problem, for the spec or for any kind of docs,
> articles etcetera?

The examples in the spec are not complete programs, and making them
into complete programs would add unnecessary padding.  So I'm not sure
it's a good idea there.

Once I understood how it worked, I came to like the way that `present` handles only showing the relevant code while still having the whole source available to the playground.  It's probably a lot of effort for the spec, but a similar technique could be used.

 

For other docs, like Effective Go, it could be done.  If you look at
the Effective Go source, you will see that it uses {{code}} links to
bring in programs.  We could perhaps modify godoc to link to the
playground for those if think it would be useful.

Ian

--
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[minux]

On Thu, Feb 14, 2013 at 12:31 AM, Kyle Lemons <kev...@google.com> wrote:

On Wed, Feb 13, 2013 at 6:46 AM, Ian Lance Taylor <ia...@google.com> wrote:

On Wed, Feb 13, 2013 at 4:54 AM,  <itmi...@gmail.com> wrote:
>
> There are a number of examples in the spec.
> For the local version of the spec, it makes sense to have the examples
> "hardcoded" in the page.
> For the online version, using golang playground for examples, would that
> potentially be a future problem, for the spec or for any kind of docs,
> articles etcetera?

The examples in the spec are not complete programs, and making them
into complete programs would add unnecessary padding.  So I'm not sure
it's a good idea there.

Once I understood how it worked, I came to like the way that `present` handles only showing the relevant code while still having the whole source available to the playground.  It's probably a lot of effort for the spec, but a similar technique could be used.

perhaps it will require some work, but this is definitely a feature worth having.

i filed https://code.google.com/p/go/issues/detail?id=4801.

[Andrew Gerrand]

This is on the docs road map; not for the spec specifically, but for future articles. All the infrastructure is there. I am working on the UI elements at the moment.

Andrew

[minux]

Hi Andrew, is the roadmap available publicly?

[Andrew Gerrand]

It only exists in my head :-)

[Brendan Tracey]

I'd like to add that I think the effective go and go tour documents could use some help. Now that I've been coding in go for a while it's not so bad, and I find the documents useful, but when I was just starting I felt like neither of the documents really answered my questions. The tour of go seems to be trying to occupy both the space of teaching someone how to get started, and being an overview of the language for CS people. It seemed to me that it's too detail heavy to be a great tour, but too detail light to be a good introduction to the language. I feel like there's room to split the tour into two, one that's just a tour for the person with casual interest, and another that's more detailed for those who are trying to write their first programs. I'm not sure how effective go fits in. I think parts of it are great right now, for example some of the "best practices", and some of the little tricks, but it could use more of "I'm used to doing thing X in Y language, how do I do it in Go?" This would be especially useful for people coming from class-oriented languages. Lastly, I don't know if I'm the only one, but I think the standard library could greatly benefit from having coding examples. I don't know if something similar could happen in go, but Matlab has two different versions of help. They have "help Foo", which gives a short description, much like the current standard library, and they have a "doc Foo" which opens up a more detailed documentation, including implementation details, usage examples, example outputs, etc. Having both is useful, as sometimes you're just trying to figure out parameter order (or whatever), and sometimes you want to know more about what is going on. 

[Andrew Gerrand]

Thanks for the feedback. It is valuable.

--

[nvcnvn]

The need of the examples mentioned in many articles.

Golang, on my own, is a language for those who already know another language.

The lack of examples for the standard library caused many difficulties for those who do not speak English (like me) when approaching a new language.

It's not fair to compare this problem with the other while Golang too young and have too much to do with the language itself. But indeed our documentation slightly poor than PHP, Python basic examples or topics like "How to ..." for C # and Java.

Some of them (PHP, Ruby..) also allow users to send comments or example. Its simpler and quicker than contribute the project.

[Nate Finch]

Other languages is a really good point.  Is there infrastructure for translating golang.org and the docs etc into other languages? I'm sure you'd have lots of people willing to help (unfortunately I'm useless in anything but English).

[minux]

On Fri, Feb 15, 2013 at 10:45 AM, Nate Finch <nate....@gmail.com> wrote:

Other languages is a really good point.  Is there infrastructure for translating golang.org and the docs etc into other languages? I'm sure you'd have lots of people willing to help (unfortunately I'm useless in anything but English).

Nothing yet.

The Chinese community maintains a Chinese translation of tip.golang.org at zh-golang.appspot.com