Roadmap for our language/ docs

[smls]

With the number of language docs steadily increasing (yay!), I think we've reached the point where we need to bring in some organization and think about where we want to go with them as a whole.

Roughly following the lead of perldoc (and the way we're heading already), I've identified three main types of language docs that we should have:

• Language reference docs - Each of these covers a certain aspect of the language itself...
  • comprehensively (including any relevant low-level and advanced stuff; but merely summarizing/linking info that is already covered by API docs)
  • in a structured way (i.e. using subsections with uniform technical names, that can be easily linked to and ideally be read out-of-context)
  • showing only short/abstract example snippets (linking to tutorials/FAQs for longer and more practical examples)
• Tutorials - Each of these approaches an area of Perl 6 programming...
  • in a more casual, free-form way (subsections can be considered to build upon each other sequentially, and be named humorously etc.)
  • not comprehensively (things are introduced as convenient; low-level/advanced/unusual things not at all or merely in the form of a "See Also" at the bottom)
  • showing practical example code
  • going beyond just documenting language features (e.g. showing how to build practical solutions from generic building-blocks; employing CPAN modules, etc.)
• FAQs - answering common questions and showing simple stand-alone solutions/recipes for common programming problems (or recommending appropriate CPAN modules).

So without further ado, here's my proposal for the "language docs" hierarchy we should be aiming for:

---

Language Reference: Fundamentals
syntax	Syntax	General syntax overview
terms	Terms	Literals and other built-in terms
operators	Operators	Infixes, prefixes, postfixes, and more!
variables	Variables	Declaring and using identifiers to store data
control	Control Flow	Statements used to control the flow of execution
quoting	Quoting Constructs	Writing strings, word lists, and regexes
routines	Routines	Working with reusable code units
types	Type System	Type constraints, subtypes, and more!
objects	Object Orientation	Objects, classes, and roles
exceptions	Exceptions	Handling errors and failures
modules	Modules	Creating, using and distributing Perl 6 modules
Language Reference: Data model
values	Value Types	Generic numbers, strings, and more!
structures	Data Structures	Generic arrays, hashes, and more!
subscripts	Subscripts	Accessing data structure elements by index or key
iterating	Iterating	Traversing data structures and sequences
containers	Container System	Lvalues, binding, and more!
nativetypes	Native Types	Machine precision numbers & tightly packed arrays
Language Reference: Domain-specific Features
regexes	Regexes	Pattern matching against strings
grammars	Grammars	Parsing and interpreting text
files	Files and Directories	Reading, writing, listing, modifying files
system	System Interaction	Terminals, pipes, processes, and more!
concurrency	Concurrency	Concurrency and asynchronous programming
testing	Testing	Writing and running unit tests
math	Math	Overview of math-related language features
temporal	Date and Time	Timekeeping, calendar math, and more!
setbagmix	Sets, Bags, and Mixes	Unordered collections of unique and weighted objects
mop	Meta-Object Protocol	Introspection, and the underpinnings of the object system
nativecall	Native Calling Interface	Call into dynamic libraries that follow the C calling convention
Tutorials
tut-intro	Tutorial: First Steps	A gentle introduction to Perl 6
tut-class	Tutorial: Classes & Objects	Creating and using classes
FAQ
faq-general	FAQ: General	General Questions About Perl 6	#112
faq-start	FAQ: Getting Started	Obtaining, learning, and adapting to Perl 6	#112
faq-why	FAQ: Justifications	Why things are the way they are in Perl 6	#112
faq-basic	FAQ: Basic Language Usage	General Perl 6 programming issues	#112
faq-data	FAQ: Data Manipulation	Dealing with data structures and data munging	#112
faq-regex	FAQ: Regexes & Grammars	Issues related to regexes and grammars	#112
faq-file	FAQ: Files and File formats	Dealing with files, filesystems and file formats	#112
faq-sys	FAQ: System Interaction	Interacting with the running computer system	#112
faq-net	FAQ: Web & Networking	Dealing with the Web, Email & networks	#112
Appendix
5to6	Perl 5 to Perl 6 Translation	How do I do what I used to do?
cheatsheet	Cheatsheet	Perl 6 at a glance
glossary	Glossary	Glossary of Perl 6 terminology
about	About the Docs	Documentation for the Perl 6 Documentation Project

---

Notes:

• Pages that already exist in some form (even with a different name, or in bad shape), are linked accordingly. Non-linked ones would be completely new. Update: added a column for links to dedicated github issue pages. Will try to keep this updated.
• The "Language Reference: Domain-specific Features" group will likely end up including a whole bunch of additional pages that I didn't think of on the spot. At some point in the future, we'll probably want to split that one up into multiple groups - but no need to rush that, and it won't affect the overall hierarchy.
• The "Tutorials" group will also grow much larger, but I don't think it will need subsections.
• Obviously, to achieve the desired result we'll need to extend htmlify to allow showing a structured index (with the groups, and the position of each page within each group, well defined) for /language instead of a flat alphabetical list. But that's a story for a separate github issue; this one is meant for the content, and the general vision for where we should head with our language docs.

So... Is this a plan which you (other p6doc contributors) could get behind?

[jonathanstowe]

I'm with this. I think there are some more domain specific thingies (such as Networking and so forth,) I've sorta kinda started a networking page, maybe I'll stick it in next week.

[stmuk]

Broadly I see the needed documentation as reflecting the great trio of O'Reilly Perl 5 books.

1. "Programming Perl" (Reference) - https://github.com/perl6/doc/
2. "Learning Perl" (Tutorial) - https://github.com/perl6/book/
3. "Perl Cookbook" (Examples) - https://github.com/perl6/perl6-examples

So some of this documentation exists. However it's extremely incomplete and needs much work particularly the Tutorial which ships with Star as a PDF.

There is a lot of good documentation hidden in the #perl6 irc channel logs as well.

Perl6 has a further danger in that google queries frequently pull outdated and inaccurate old documentation from the last 15 years.

I'd recommend use of Duckduckgo which even has some basic perl6 doc support (see https://duck.co/ia/view/perl6doc)

[smls]

I've sorta kinda started a networking page

Hm. What networking-related Perl 6 language features are there to document?

If your doc is mostly just demonstrating how to use 3rd-party modules like HTTP::UserAgent for common tasks like "How can I download a webpage?", it should be converted into FAQ entries in faq-basic or faq-net.

If it walks readers through the process of building such networking functionality using generic Perl 6 features, it should be a Tutorial.

Language reference pages should stick to documenting built-in Perl 6 language features.

PS: Updated the OP to clarify.

[jonathanstowe]

I agree with your second paragraph.

I think there needs to be a page to bring together the network related parts of the core library, so people can find the details of the classes.

But I'm fine not doing it, I have other things to do.

[smls]

I still have no idea what "network related parts of the core" you're talking about... But maybe that's because it's too hot here for me to think clearly right now... :P

I don't want to keep you from writing documentation - just trying to get us to use a consistent scheme for where and how to present what type of documentation. Of course since we're using a git repo, there's no harm in just adding the page the way you imagine it. If it doesn't end up fitting into the larger scheme, it can always be refactored...

[skids]

Looks good. My only wonder is whether 5to6 should be in the Tutorial section rather than the Appendix.

[ghost]

Looks good - I think 5to6 definitely belongs in the appendix than in the tutorials since tutorials can ideally be read by people without any knowledge of perl5. For those with perl5 knowledge, they can look them up in appendix. Atleast, that's what I think was the idea in adding them to appendix.

[ab5tract]

@smls are you saying that there are no network related functionalities in core?

~/c/p/r/src> find . | grep Socket
./core/IO/Socket
./core/IO/Socket/Async.pm
./core/IO/Socket/INET.pm
./core/IO/Socket.pm

Why should this necessarily be a tutorial and not just a 'networking with only CORE-setting' in the Language section?

It seems to me that a tutorial about building a networking library could easily go to tutorial, but I don't see any clear line in the sand separating 'networking' from 'core language features'

[smls]

@ab5tract I'm saying I didn't know; that's why I asked... :P If there are multiple classes for sockets in core, then yes, it would probably make sense to have a language reference page for that (in the "domain-specific" section). But whether that page should be called networking or sockets, would depend on whether those classes can also be used for non-networking stuff (e.g. IPC) and whether there are other networking features in core that would want -to be documented together with those classes. (Again, I don't know.)

@skids I could definitely imagine a 5to6 tutorial - but I don't think that's what our current 5to6 doc is (it's very much a straight-up reference doc). Maybe we should have both? The current 5to6 (completed of course) in Appendix, and a new (shorter, friendlier, more tutorial-like) tut-5to6 in Tutorials.
I also realize that the group name "Appendix" is not perfect (I first had it as "Special Reference & meta Docs"), but at least it's short, and as long as the number of pages in that group stays small I think it's fine.

[dha]

The overall structure looks good to me at first glance. I'm sure as time goes on, many (including me, perhaps) will find some tweaking to be done, but I think it's a good starting point.

As far as 5to6 is concerned, just so you know, I've been wanting to write a "Perl 6 Essentials for Perl 5 Programmers" document of some sort, but looking at it the other day, it seems to me that the current 5to6 is a good start on that. I've got a list of topics off the top of my head that maybe should be added (https://github.com/dha/perl5-to-perl6-docs/blob/master/5to6Additions.txt), and I'm planning on looking at that in the coming week. And, for anyone who's missed it, I've gone through Perl 5's perlfunc, perlop, and perlsyn and noted the differences between P5 and P6 (available at https://github.com/dha/perl5-to-perl6-docs).

tl;dr: Good idea. We should definitely start doing something along these lines. :-)

[AlexDaniel]

This list is great. Surprisingly, it is also more or less up-to-date. We should continue working on it.

[AlexDaniel]

We should turn this into a TODO list.

[rafaelschipiura]

• syntaxSyntax

• termsTerms

• operatorsOperators

• variablesVariables

• controlControl Flow

• quotingQuoting Constructs

• routinesRoutines

• typesType System

• objectsObject Orientation

• exceptionsExceptions

• modulesModules

• valuesValue Types

• structuresData Structures

• subscriptsSubscripts

• iteratingIterating

• containersContainer System

• nativetypesNative Types nativeInt (int) is the only native type that is documented #1512

• hashmap Hashes and maps Make a new language/hashmap #1682

• regexesRegexes

• grammarsGrammars

• filesFiles and Directories

• systemSystem Interaction

• concurrencyConcurrency

• testingTesting

• mathMath

• temporalDate and Time

• setbagmixSets, Bags, and Mixes

• mopMeta-Object Protocol

• nativecallNative Calling Interface

• tut-introTutorial: First Steps

• tut-classTutorial: Classes & Objects

• faq-generalFAQ: General Add FAQ pages (like the ones perldoc has) #112

• faq-startFAQ: Getting Started Add FAQ pages (like the ones perldoc has) #112

• faq-whyFAQ: Justifications Add FAQ pages (like the ones perldoc has) #112

• faq-basicFAQ: Basic Language Usage Add FAQ pages (like the ones perldoc has) #112

• faq-dataFAQ: Data Manipulation Add FAQ pages (like the ones perldoc has) #112

• faq-regexFAQ: Regexes & Grammars Add FAQ pages (like the ones perldoc has) #112

• faq-fileFAQ: Files and File formats Add FAQ pages (like the ones perldoc has) #112

• faq-sysFAQ: System Interaction Add FAQ pages (like the ones perldoc has) #112

• faq-netFAQ: Web & Networking Add FAQ pages (like the ones perldoc has) #112

• 5to6Perl 5 to Perl 6 Translation

• cheatsheetCheatsheet

• glossaryGlossary

• aboutAbout the Docs

• contexts Contexts and contextualizers: Document contexts #1225

[JJ]

This means that there are still quite a pile of documents to go, right? Working up from the bottom I see cheatsheet, for instance. Pretty much all FAQs, too.

[tisonkun]

FWIW, tut-intro can be referred to https://github.com/hankache/perl6intro

I think our docs under /languages/ are more like talks, not API docs.

We have overlap docs on grammar and OOP while make/made and more details about OOP not documented.

FAQ page now is a Wiki page, and yes, all FAQs mentioned above are covered, though might not be in FAQ page.

[JJ]

So what do you suggest? Just wipe out all FAQs or point them to the wiki and then proceed with the rest of the uncovered pages?

[tisonkun]

#112 which has been closed solved those about FAQ, so I modify the todo list.

BTW, I link tut-intro to http://perl6intro.com/

[rafaelschipiura]

The last two tasks have been split into new issues. #2069 #1512