Created
November 9, 2014 13:28
-
-
Save anonymous/b18d6d46975dbd6c06ec to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
So, back in Dec/2013 there was this specs PR: | |
https://github.com/perl6/specs/pull/62 | |
The author proposes revising the synopses introductions. Unfortunately, | |
he doesn't seen to have committed the changes into the repository. But | |
I think his idea is a good one. | |
Is this desired in the long run or do you think that each synopsis should | |
have its own independent start material? | |
If the beginnings of all synopses were to be normalized together, | |
in your opinion, what should the section right after VERSION be | |
named? Introduction, overview, summary, description, synopsis, roadmap, | |
about this document, tl;dr, or something else? Should the heading be | |
ALLCAPS or Title-cased? Some of these don't make too much sense in this | |
context, I'm just generating some ideas. | |
My intention was to have an introductory material to "hold hands" | |
with the reader for one paragraph or two, before he enters the main | |
text. Maybe something like "This synopsis deals with foo, bar, baz. Foo | |
is this... Bar is that... etc." | |
Ideas for formatting this text could be extracted from CPAN modules | |
documentation, Perl 5 manpages, and Camel book chapters. | |
A number of synopses already contain an "Overview" section, should this | |
be the one to adopt? Some of them starts some text right after the | |
VERSION section without any intervening =head1 title. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment