No books mentioned in Perl 6 documentation

[lizmat]

Perhaps it would be an idea to create a page about all of the Perl 6 books that have been written / are available?

[AlexDaniel]

Yeah, at least a FAQ entry with a link to https://perl6book.com/

[lizmat]

Actually, I was thinking a little more than that.

[zoffixznet]

Side note: we have a Resources page on the main site that mentions a whole bunch of other learning resources (including books).

[JJ]

@zoffixznet we can take the books part from there. @lizmat something like that would be OK?

[zoffixznet]

@zoffixznet we can take the books part from there

My point was: what's so special about books? Why are we duplicating books on the docs site but none of the other resources? The entire Resources page should be moved, if needed, or the docs site should make it more obvious where to find all the other resources.

[stmuk]

I've added a reference to that site to the faq but generally think we shouldn't be duplicating resources such as perl6book.com.

[lizmat]

FWIW, external resources can disappear at any moment. As far as I am concerned, perl6book.com should be part of the general perl6.org site, and not an external one.

…

On 6 Jul 2018, at 14:40, Steve Mynott ***@***.***> wrote: I've added a reference to that site to the faq but generally think we shouldn't be duplicating resources such as perl6book.com. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[nxadm]

Putting books in something like resources is fine. In the doc, not so. Books age way too fast. Also, while many are great some can be awful. Putting them in doc required an editorial stance (as reviewing and vetting them).

[moritz]

How do you feel about referencing specific books where they make sense? Like the parsing book on the regexes + grammar page?

[nxadm]

I think a short description would make sense in the resources. It's a natural place to promote books about the language. They can be categorized according to domain once there are enough books.

On the proper language doc, however, I don't think they are a good fit, because:

• the referenced book may not be freely available (cost, license, out-of-print).
• we may end referencing to outdated info (editorial/vetting task).
• which specific book do we reference (editorial/vetting task)? Do we reference all of them?

[moritz]

@lizmat if you want to integrate the book info into the docs page, you should only do that with the published books, not the upcoming ones

[AlexDaniel]

How do you feel about referencing specific books where they make sense? Like the parsing book on the regexes + grammar page?

I'm against this, please no product placement in docs (even if we like the book very much). As a doc reader I'd feel rather uneasy if I was directed to a paid resource.

If the book is open-source then we can talk, although in that case maybe it's better to borrow needed sections to make our docs self-sufficient.

I don't mind having a list or pointing to a list of books, just not embedded on actual doc pages.

[JJ]

Let's see if we have a kind of consensus here:

• There should be some FAQ entry, pointing to some resource of which we do have control (that is, in the perl6.org domain)
• It's OK to mention books in the docs, as long as they are open source.

[nxadm]

It's OK to mention books in the docs, as long as they are open source.

I think that docs should be self-contained.

[moritz]

@nxadm I think self-contained is over-ambitious. The docs link to several external sources already, for example Wikipedia to explain MRO, C3, Bytecode and other concepts.

[nxadm]

@moritz There is a difference between deeper computer science subjects and the explanation of features of the language itself (e.g. in the case in a Perl6 only feature).

[bazzaar]

Why not have a separate section in the docs entitled ‘external Perl6 documentation’, this could be further subdivided by subject topics. These could contain links and maybe a few words to the external documentation (books/blog articles/videos). A single external resource might be referenced in more than one of the subject topics. Then within the main body of the docs, it would be possible just to provide a link to an appropriate subject topic in the ‘external Perl6 documentation’ section. If we have a collection of excellent Perl6 resources (books, IDE app, tutorials, whatever) we should try to integrate them in some way. The sum of all parts is greater that way. Regards, Barry

…

On 7 Jul 2018, at 10:12, nxadm ***@***.***> wrote: @moritz There is a difference between deeper computer science subjects and the explanation of features of the language itself (e.g. in the case in a Perl6 only feature). — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[JJ]

@bazzaar It might be a good idea, but it's tangential to the original post. While books can be considered "external resources" and thus be part of the new page you mention, it's actually a different thing that probably deserves a different issue.

[bazzaar]

I was trying to find a halfway house, keeping the docs self-contained, yet allowing at a granular level in the docs the placement of links to find external material. I saw the discrete ‘external Perl6 documentation’ page as one solution but the key it’s organisation into topics and subtopics, and the use of that structure as the adapter to interface with the rest of the docs. A granular link at any place in the docs would therefore not point to a single external address, rather to an internal address that would provide the reader with a short list of relevant external material for further consideration.

…

On 7 Jul 2018, at 13:06, Juan Julián Merelo Guervós ***@***.***> wrote: @bazzaar It might be a good idea, but it's tangential to the original post. While books can be considered "external resources" and thus be part of the new page you mention, it's actually a different thing that probably deserves a different issue. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[JJ]

@bazzaar you pardon the pun, but it's more an outhouse instead of a halfway house
I have finally added it as a FAQ. The problem with your proposed resources page, or a books page, is that it's difficult to categorize within the current doc framework. We have either language or type resources, and then a third leg which is not heavily used, "program". Resources don't really match any of these categories, although language could seem one and in fact we have a Community page there.
But anyway my point is that an "External resource" page needs its very own issue, to discuss these things, as well as which resources would be interesting to include (or whether doing at all), so it's really better if you open a different issue if you think it's worth discussing and actually implementing it.

[AlexDaniel]

@JJ but now the list is duplicated? I don't like the idea of having the same list on https://perl6.org/resources/ and in the FAQ of the docs.

[JJ]

@AlexDaniel what do you want then? It's not duplicated, because I have eliminated those that are in progress. Adn the list is only title and link, how can you not duplicate it? Maybe add some comment?

[AlexDaniel]

@JJ either have the list on https://perl6.org/resources/ and link to it from the docs, or remove the list from https://perl6.org/resources/ and leave a link to the docs.

[JJ]

1. That list is on a frame. Can't be properly linked. 2. It includes work in progress. 3. What's the problem with listing books in two places? El lun., 9 jul. 2018 19:29, Aleks-Daniel Jakimenko-Aleksejev < notifications@github.com> escribió:

…

@JJ <https://github.com/JJ> either have the list on https://perl6.org/resources/ and link to it from the docs, or remove the list from https://perl6.org/resources/ and leave a link to the docs. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2143 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAB9GESJuw9mH_-LcMqgT7INs9ryXaNks5uE5L7gaJpZM4VCwtm> .

[JJ]

Also, two different sites. If after this list, someone decides to remove it from Perl 6.org, it's a different thing altogether El lun., 9 jul. 2018 19:29, Aleks-Daniel Jakimenko-Aleksejev < notifications@github.com> escribió:

…

@JJ <https://github.com/JJ> either have the list on https://perl6.org/resources/ and link to it from the docs, or remove the list from https://perl6.org/resources/ and leave a link to the docs. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2143 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAB9GESJuw9mH_-LcMqgT7INs9ryXaNks5uE5L7gaJpZM4VCwtm> .