It might be good to have a style guide for people (such as myself) who are contributing POD content to this repo, so the "finished" docs end up in a consistent and professional state.
Here are a few "questions" that imo should be covered by such a guide (though I don't have good answers for all of them):
Structure
How to document multiple similar routines
I'd suggest making it a guideline to avoid wtiting a routine's documentation in the form
Like [other method] except [...]
even when they're in the same class, because readers might not read the whole class page, but rather navigate to a specific routine (maybe even out of context in the /routine/ section of the website) and expect it to tell them how it works without being sent on a goose chase around the site.
In other words, give each routine documentation a self-contained introduction, and only link to related/similar routines below that introduction, even if that means duplicating some half-sentences multiple times.
Language
How to refer to the concept of only using the .Bool/.Num/etc. coercion of a value and discarding the original information
Compare:
- "it evaluates the value in boolean/numeric context"
- "it boolifies/numifies the value"
- "it uses the truthy/numeric value"
- "it reduces the value to its boolean/numeric equivalent"
Are all of these sufficiently professional and newbie-friendly? Which is preferred?
Whether to write 'parameter' vs 'argument'
I recently came across this in S06:
S06: "In Perl 6 culture, we distinguish the terms parameter and argument; a parameter is the formal name that will attach to an incoming argument during the course of execution, while an argument is the actual value that will be bound to the formal parameter. The process of attaching these values (arguments) to their temporary names (parameters) is known as binding. (Some C.S. literature uses the terms "formal argument" and "actual argument" for these two concepts, but here we try to avoid using the term "argument" for formal parameters.)"
I'd suggest we follow the spec here from now on, and make this an official guideline for p6doc.
Whether to write 'object' vs 'value'
Is it OK to use "objects" as an umbrella term for instances of any Perl 6 type, including immutable value types?
Or should it be reserved for reference types, and be replaced with the phrase "objects/values" whenever we're talking about both reference and value types?
(See the introduction of /type/Set for an example of this usage, though this shouldn't be seen as a recommendation.)
Whether to use past tense or present tense when talking about Perl 5 features
Compare:
- "In Perl 5 this was used for ..., but in Perl 6 ..."
- "In Perl 5 this is used for ..., but in Perl 6 ..."
Slipping into the past there can be tempting when writing such docs, but I think we should avoid it, as it misrepresents the development status of Perl 5 (which is actively maintained both now and probably for a long time to come), and could come across as needlessly abrasive to Perl 5 programmers.
Formatting
How to show output of sample code lines
Currently, we tend to use normal # comments both for annotating code, and for showing its output:
my @a = 2, 4, 6; # creates a new array
say @a.WHAT; # (Array)
Though I think I've also seen this convention used somewhere:
my @a = 2, 4, 6; # creates a new array
say @a.WHAT; #> (Array)
It could avoid ambiguity, and while it is a little uglier by itself, htmlify could detect it so we could give it special CSS rendering (think dark background with light text like a terminal) that would make its purpose extra clear to readers.
Would it be worth it?