New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Roadmap for our language/ docs #114

Closed
smls opened this Issue Aug 6, 2015 · 31 comments

Comments

Projects
None yet
@smls
Contributor

smls commented Aug 6, 2015

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

syntaxSyntaxGeneral syntax overview
termsTermsLiterals and other built-in terms
operatorsOperatorsInfixes, prefixes, postfixes, and more!
variablesVariablesDeclaring and using identifiers to store data
controlControl FlowStatements used to control the flow of execution
quotingQuoting ConstructsWriting strings, word lists, and regexes
routinesRoutinesWorking with reusable code units
typesType SystemType constraints, subtypes, and more!
objectsObject OrientationObjects, classes, and roles
exceptionsExceptionsHandling errors and failures
modulesModulesCreating, using and distributing Perl 6 modules

Language Reference: Data model

valuesValue TypesGeneric numbers, strings, and more!
structuresData StructuresGeneric arrays, hashes, and more!
subscriptsSubscriptsAccessing data structure elements by index or key
iteratingIteratingTraversing data structures and sequences
containersContainer SystemLvalues, binding, and more!
nativetypesNative TypesMachine precision numbers & tightly packed arrays

Language Reference: Domain-specific Features

regexesRegexesPattern matching against strings
grammarsGrammarsParsing and interpreting text
filesFiles and DirectoriesReading, writing, listing, modifying files
systemSystem InteractionTerminals, pipes, processes, and more!
concurrencyConcurrencyConcurrency and asynchronous programming
testingTestingWriting and running unit tests
mathMathOverview of math-related language features
temporalDate and TimeTimekeeping, calendar math, and more!
setbagmixSets, Bags, and MixesUnordered collections of unique and weighted objects
mopMeta-Object ProtocolIntrospection, and the underpinnings of the object system
nativecallNative Calling InterfaceCall into dynamic libraries that follow the C calling convention

Tutorials

tut-introTutorial: First StepsA gentle introduction to Perl 6
tut-classTutorial: Classes & ObjectsCreating and using classes

FAQ

faq-generalFAQ: GeneralGeneral Questions About Perl 6#112
faq-startFAQ: Getting StartedObtaining, learning, and adapting to Perl 6#112
faq-whyFAQ: JustificationsWhy things are the way they are in Perl 6#112
faq-basicFAQ: Basic Language UsageGeneral Perl 6 programming issues#112
faq-dataFAQ: Data ManipulationDealing with data structures and data munging#112
faq-regexFAQ: Regexes & GrammarsIssues related to regexes and grammars#112
faq-fileFAQ: Files and File formatsDealing with files, filesystems and file formats#112
faq-sysFAQ: System InteractionInteracting with the running computer system#112
faq-netFAQ: Web & NetworkingDealing with the Web, Email & networks#112

Appendix

5to6Perl 5 to Perl 6 TranslationHow do I do what I used to do?
cheatsheetCheatsheetPerl 6 at a glance
glossaryGlossaryGlossary of Perl 6 terminology
aboutAbout the DocsDocumentation 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

This comment has been minimized.

Contributor

jonathanstowe commented Aug 6, 2015

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

This comment has been minimized.

Contributor

stmuk commented Aug 6, 2015

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

This comment has been minimized.

Contributor

smls commented Aug 6, 2015

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

This comment has been minimized.

Contributor

jonathanstowe commented Aug 6, 2015

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

This comment has been minimized.

Contributor

smls commented Aug 6, 2015

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

This comment has been minimized.

Contributor

skids commented Aug 6, 2015

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

@svatsan

This comment has been minimized.

Member

svatsan commented Aug 6, 2015

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

This comment has been minimized.

Contributor

ab5tract commented Aug 7, 2015

@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

This comment has been minimized.

Contributor

smls commented Aug 7, 2015

@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

This comment has been minimized.

Contributor

dha commented Aug 8, 2015

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

@smls smls referenced this issue Aug 10, 2015

Closed

Document the GLR #116

@awwaiid awwaiid assigned awwaiid and unassigned awwaiid Dec 21, 2015

@autarch autarch referenced this issue Dec 29, 2015

Merged

rb-nutshell #288

@AlexDaniel AlexDaniel added docs and removed affects content labels Jun 24, 2016

@AlexDaniel

This comment has been minimized.

Member

AlexDaniel commented Jul 1, 2016

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

AlexDaniel added a commit that referenced this issue Jul 5, 2016

WANTED file is not needed anymore (#657)
Here is the summary of all items in WANTED list (and reasons why we do not
need to list them anymore):

Tutorials:
    * general Perl 6 intro 〈listed in #114〉
    * multis / multi dispatch, how to use them practically 〈/language/functions#Multi-dispatch as well as /type/Signature#Type_Constraints〉
    * lazy lists and generators 〈issue #667〉
    * concurrency 〈/language/concurrency〉
    * IO 〈/language/io〉
    * network programming (e.g., examples for IO::Socket::INET) 〈#114 lists “FAQ: Web & Networking: Dealing with the Web, Email & networks”, that's probably enough〉
    * MOP 〈/language/mop〉
    * When to use which Set/Bag/*Hash type 〈#668〉
    * Regexes and grammars (can be partially stolen from perl6/book) 〈language/regexes and language/grammars〉
    * Pod6 〈#669
    * Exceptions 〈/language/exceptions〉
    * Updated version of http://perl6advent.wordpress.com/2010/12/22/day-22-the-meta-object-protocol/ (RT #121967) 〈not relevant anymore? no such example in the docs〉
    * OS portability details 〈#670

Syntax features:
    * Hyper Operators (prefix, infix, postfix and method call) 〈language/operators#Hyper_Operators〉
    * $*ARGFILES, lines()   (Issue #96) 〈issue #96 is closed〉
    * dispatch related declarators:  multi, only, proto, method, etc... 〈#634 #671〉
    * Smartmatching: ~~, allowed RHS values, backlinks from related docs (grep) 〈#672〉

API docs:
    * KeyReducer 〈#673〉
    * Uni 〈/type/Uni ?〉

Functions:
    * srand() 〈#674〉
    * use [probably really important...] 〈what?〉
    * on (S17) 〈we have /language/concurrency, it is probably good enough〉
    * duckmap() and deepmap() 〈#675 #676〉

Miscellaneous:
    * Add TODO comments to undocumented items ("=comment TODO") (Have started - dha) 〈we now use github issues instead〉

@AlexDaniel AlexDaniel referenced this issue Jul 20, 2016

Closed

Complete Glossary page #728

99 of 99 tasks complete
@AlexDaniel

This comment has been minimized.

Member

AlexDaniel commented Sep 3, 2017

We should turn this into a TODO list.

@rafaelschipiura

This comment has been minimized.

Contributor

rafaelschipiura commented Sep 5, 2017

@JJ

This comment has been minimized.

Contributor

JJ commented Jan 26, 2018

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

This comment has been minimized.

Contributor

TisonKun commented Jan 26, 2018

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

This comment has been minimized.

Contributor

JJ commented Jan 27, 2018

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

This comment has been minimized.

Contributor

TisonKun commented Jan 28, 2018

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

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

JJ added a commit that referenced this issue May 24, 2018

Adds set algebra to the Math page
Which might or might not be what someone 1000 days ago had in mind,
but it's at least what I would like to find if I go looking for math
stuff in Perl 6. This refs #114, but still a lot TBD.

JJ added a commit that referenced this issue May 24, 2018

JJ added a commit that referenced this issue May 24, 2018

JJ added a commit that referenced this issue May 24, 2018

Finishes the first version of the math page
This refers to #114. Will check this page now and move on to the
next. If think it can be improved, please open a different issue for
that.

JJ added a commit that referenced this issue May 25, 2018

JJ added a commit that referenced this issue May 25, 2018

Adds content to the sequences section
Also learns new words. Refs #114

JJ added a commit that referenced this issue May 25, 2018

JJ added a commit that referenced this issue May 25, 2018

Finishes first full version of the system interaction page.
Refs #114. It's rather brief and not (never) perfect, but it's a good
guide on how to interact with the system. I'll check this page now and
move on to the next one.

JJ added a commit that referenced this issue May 25, 2018

Finishes first full version of the system interaction page.
Refs #114. It's rather brief and not (never) perfect, but it's a good
guide on how to interact with the system. I'll check this page now and
move on to the next one.

JJ added a commit that referenced this issue May 25, 2018

Start rewriting of the hashmap language page
Follows #1682 advice of moving the top-heavy part of the Hash type to
this page. That part has been rewritten in similarity to Array, by
making references to its general behavior using parallelisms between
them. This also goes towards fulfillment of the roadmap #114

JJ added a commit to JJ/my-perl6-examples that referenced this issue May 26, 2018

JJ added a commit that referenced this issue May 26, 2018

Completed hashmap page
This closes #1682. Also advances towards the end of #114, which seems
closer and closer.

JJ added a commit that referenced this issue May 27, 2018

JJ added a commit that referenced this issue May 27, 2018

JJ added a commit that referenced this issue May 27, 2018

JJ added a commit that referenced this issue May 27, 2018

JJ added a commit that referenced this issue May 27, 2018

JJ added a commit that referenced this issue May 28, 2018

JJ added a commit that referenced this issue May 28, 2018

JJ added a commit that referenced this issue May 28, 2018

JJ added a commit that referenced this issue May 28, 2018

JJ added a commit that referenced this issue May 28, 2018

JJ added a commit that referenced this issue May 28, 2018

JJ added a commit that referenced this issue May 28, 2018

Finishes introspection
Adds some links and examples. Refs #114

JJ added a commit that referenced this issue May 28, 2018

Moves the reification tutorial glossary → structures
Which is probably a better place for it. Refs #114

JJ added a commit that referenced this issue May 28, 2018

Document on data structures is completed.
I would be happy as a clam if this closed an issue, but it only means
a feeble tick in the humongous #114. However, closer to the end, with
just a couple of pages to go...
@rafaelschipiura

This comment has been minimized.

Contributor

rafaelschipiura commented May 29, 2018

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

JJ added a commit that referenced this issue May 30, 2018

Adds documentation for nativesize
Only in the way of explanation of the difference between native types
and native types with native size; added warning that it's not
spec. But this would close #2051.

I am going to close #1512 too. It does document all native types, and
clarifies the difference between them. This would be the last document
in #114, which was already closed, so I can't close it, but this would
basically be it. As the rest of the documents I have created, it's not
perfect, but it's there. It can be incrementally improved from now on.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment