3^rd in # lines perl6/doc

1^st in # issues closed

:10things you can learn while working in the Perl 6 documentation too

Sponsored by The Perl Foundation

Documenting a language into existence

Documentation is important

Really important

From mr_chromatic

Writing good documentation is difficult and keeping it current is time consuming, but it helps get and keep users even if library support, performance, platform support, and community size all need improvement.

The community speaks

Thinking about dinosaurs

Don't want to see my Perl 6 dinosaurs after :10years

Second thing I learned

Perl 6

Using a pet project to learn a language

Docs aren't written by those who know

But by those who can

grammar HasOur {
    token TOP {
        :our $our = 'þor';
        $our \s+ is \s+ mighty
    }
}

say HasOur.parse('þor is mighty');
say $HasOur::our;

And you can see the dinosaur right there

But I also learned...

Every other language in the world

awk

my $fixer = Proc::Async.new('awk', 
    'BEGIN {print "!"} {print "^" gsub(/[\\:]/,"",$0)}', 
    $input-file);

There are infrequently asked questions

Go and ask in StackOverflow!

+ Anwer + Upvote

! lazyness

! impatience

! hubris

!lazy == eager?

my  @lazy-array = lazy 1, 11, 121 ... 10**100;
say @lazy-array.is-lazy;                 # OUTPUT: «True␤»
say @lazy-array[];                       # OUTPUT: «[...]␤»
my  @no-longer-lazy = eager @lazy-array; # Forcing eager evaluation
say @no-longer-lazy.is-lazy;             # OUTPUT: «False␤»
say @no-longer-lazy[];

! Laziness eq ｢Diligence｣

! Hubris

$hubris ≅ 0

git whatchanged --author="[Mm]erelo" --diff-filter=A \
    --no-commit-id --name-only | wc
     30      30     720

my \U = 'a'..'z'.Set;
sub postfix:<⁻>(Set $a) { U ⊖ $a }
my @sets;
@sets.push: Set.new( @alphabet.pick( @alphabet.elems.rand)) 
    for @alphabet;
my ($de-Morgan1,$de-Morgan2) = (True,True);
for @sets X @sets -> (\A, \B){
    $de-Morgan1 &&= (A ∪ B)⁻  === A⁻ ∩ B⁻;
    $de-Morgan2 &&= (A ∩ B)⁻  === A⁻ ∪ B⁻;
}
say "1st De Morgan is ", $de-Morgan1;
say "2nd De Morgan is ", $de-Morgan2;

Flow with the documentation

Is it documentable?

Synopsis

→ Roast

→ Rakudo

Document it!

GitHub

→ Rakudo

→ Roast

We don't want it perfect

We want it there

Is this perfect?

my @regex-check = ( /<alnum>/, /<alpha>/, /<punct>/ );
say @regex-check.map: "33af" ~~ *;
# OUTPUT: «(｢3｣␤ alnum => ｢3｣ ｢a｣␤ alpha => ｢a｣ Nil)␤»

Documentation =~= cooking

Better there (slightly charred) than order pizza

class Cook {
    has @.utensils  is rw;
    has @.cookbooks is rw;
    method cook( $food ) { return "Cooking $food";  }
    method clean_utensils { 
      return "Cleaning $_" for @.utensils; 
    }
    multi method gist(Cook:U:) { '⚗' ~ self.^name ~ '⚗' }
    multi method gist(Cook:D:) { 
      '⚗ Cooks with ' ~ @.utensils.join( " ‣ ") \ 
      ~ ' using ' \
      ~ @.cookbooks.map( "«" ~ * ~ "»").join( " and ") }
}

            

Cooks will cook

my $cook = Cook.new(
    utensils => <spoon ladle knife pan>,
    cookbooks => ['Cooking for geeks','The French Chef Cookbook']);
say Cook.gist; # OUTPUT: «⚗Cook⚗»
say $cook.gist; 
# OUTPUT: «⚗ Cooks with spoon ‣ ladle ‣ knife ‣ pan using 
# «Cooking for geeks» and «The French Chef Cookbook»␤»

We are in a complex system

Sankey diagram

Zipf is the law

Ducks do complex

say [[1, 2, [3, 4]], [[5, 6, [7, 8]]]].duckmap:
   -> $array where .elems == 2 { $array.elems };
# OUTPUT: «[[1 2 2] [5 6 2]]␤» 

Toes

JJ broke everything!

Languages are people

They have class

=begin code :preamble<class Person {
    has Int $.age;
    has Str $.name;
    method set-name-age( $!name, $!age ) {}
};
my Person $person .= new;
>
set-name-age $person: 'jane', 98;   # Indirect invocation
=end code

Programming is solving problems

Our problem → attract and keep a community

Make better code → become a better person

Big

Huge

sub thank( *%args) { say "Thanks ", %args }; thank :from('♥') 

OUTPUT: «Thanks {from => ♥}␤»