Mailing List Archive

On Oct 31, 2020, at 6:39 AM, H.Merijn Brand <perl5@tux.freedom.nl> wrote:
>
> How about not referring to older versions in the mainline of the
> descriptions, but add a bottom section with something like
>
> =head2 Older versions and changes

This sort of compromise approach is one favored by the community of documentation-writers (https://www.writethedocs.org) that I’ve been hobnobbing with over the course of this project. I raised the question on its style-guide Slack channel last week, and the majority favored the option of keeping important legacy-version information handy, but also gathering it together in a sort of “local appendix” at the end of a relevant section, much as suggested here.

(Worth keeping in mind that I posed the question in a “generic” context, not saying whether the docs were targeting the web, or pack-in material, or a book.)

As an aside, I’m cheered to see the lively discussion on this list about this particular proposed standard. I find it to clearly show both a great deal of active interest in solid, modernized documentation among Perl’s present stewards — as well as the possible need for a dedicated communication channel for it!

On Oct 26, 2020, at 8:59 PM, Jason McIntosh <jmac@jmac.org> wrote:
>
> On Oct 26, 2020, at 8:00 PM, Tony Cook <tony@develop-help.com> wrote:
>>
>> Making a PR would make it easier to comment on (and passing
>> porting/podcheck.t might fix some issues, eg. some non-literal lines
>> are over 72 characters.)
>
> Sure… barring the unexpected, I intend to make a PR before next week. It seemed appropriate to get comment on the overall gist from p5p before requesting to merge a brand-new 6,800-word Pod document into blead, though!

For the record, I submitted that pull request yesterday: https://github.com/Perl/perl5/pull/18275 Cheers to Dan Book and Graham Knop for early code review and edits.

On 10/23/20 6:17 PM, Jason McIntosh wrote:
> Dear Porters,
>
> I just completed a draft of a Perl core documentation style guide, the main deliverable of a TPF-funded project I began last month (https://news.perlfoundation.org/post/grant_proposal_documentation_standards_perl7). It, plus a handful of supporting documents and other notes and recommendations, can be found here: https://jmac.org/misc/perldoc/
>
> As that web page states, two proposals stem from this work:
>
> 1) Perl 5 Porters adopting this style guide as a standards document for Perl’s core documentation, and adding it to Perl’s source distribution as either a man page (in `pod/`) or a porting document (in `Portling/`).
>
> 2) Perl 5 Porters establishing a documentation team or manager within p5p, tasked with maintaining and improving Perl’s core documentation, and essentially running it as its own open-source sub-project within the greater Perl project.
>
> As a follow-up action, I’d like to make a pull request out of the style guide, but only after giving p5p a chance to review and comment on the work outside of a source-control context. So, please consider me very interested in any questions or comments about this work.
>
> I’d also be very happy to further discuss either of the above proposals. To be quite clear, I am interested in accepting an ongoing role regarding documentation management, should one be created.


Thank you for working on this, Jason. This thread shows both the value
and the interest we see in the Perl documentation and standardizing them.


I provided my comments elsewhere, but I want to respond here to some
concerns further down the thread:


* I agree American English vs. British English can be separately
bike-shed if we agree on standardizing it. To me, this is much like
2-space vs. 4-space indentation. I would use one of them, but I'm happy
to work on the other when following someone's guidelines (even if it
means spelling it "centre.") At the moment, I think we have mixed types.


Whichever one we pick, I think it would be valuable to note (whether by
link or short list) the primary differences such as "s" vs. "z," or
maintaining some spelling originating in French, as well as where to put
the comma or period when inside a quote, and, of course, the infamous
Oxford comma. Otherwise, I know *I* will mess it up more than once. :)


* I've seen the noting of differences with previous versions was a big
discussion point. It seems like there's room to discuss the "when
appropriate" part of it. For example, including when a capability was
added might be appropriate, while documenting how something worked on
version 5.8 is not just irrelevant but can be confusing to someone who
is picking up the language only now.


Another point to this: Other than asking, "Why do we want to put the
version here?" we might want to ask, "What type of documentation is
this?" - In a reference, it might be a shorter note (as Dave M.
suggests), while in a lengthy explanation of hash keys, it would be
valuable to explain the randomization of results and point to older
versions in which it was changed.


I suggest we keep it open and, at the very least, minimize (or
"minimise") the length of versions. Whenever I read Perl documentation
and saw older versions documented everywhere, it felt like the
documentation just wasn't up-to-date at all. ("This feature came out in
X.YY," *lookup version year*, "Oh wow, this is... 20 years old and
mentioned here as if it's new?")


I will provide other (or similar) comments on the PR.


Thanks again, Jason, and everyone involved in the thread! :)


Sawyer.

On Sun, Nov 1, 2020 at 2:13 PM Sawyer X <xsawyerx@gmail.com> wrote:

> * I've seen the noting of differences with previous versions was a big
> discussion point. It seems like there's room to discuss the "when
> appropriate" part of it. For example, including when a capability was
> added might be appropriate, while documenting how something worked on
> version 5.8 is not just irrelevant but can be confusing to someone who
> is picking up the language only now.
>
>
> Another point to this: Other than asking, "Why do we want to put the
> version here?" we might want to ask, "What type of documentation is
> this?" - In a reference, it might be a shorter note (as Dave M.
> suggests), while in a lengthy explanation of hash keys, it would be
> valuable to explain the randomization of results and point to older
> versions in which it was changed.
>
>
> I suggest we keep it open and, at the very least, minimize (or
> "minimise") the length of versions. Whenever I read Perl documentation
> and saw older versions documented everywhere, it felt like the
> documentation just wasn't up-to-date at all. ("This feature came out in
> X.YY," *lookup version year*, "Oh wow, this is... 20 years old and
> mentioned here as if it's new?")
>

These are all reasonable approaches that I agree with. It's most important
to remember that both "documenting every ancient behavior that no longer
exists" and "pretending all old versions don't exist" are counterproductive
extremes, and each case merits determining the appropriate middle ground.

-Dan

On Sun, Nov 1, 2020 at 11:13 AM Sawyer X <xsawyerx@gmail.com> wrote:

> * I agree American English vs. British English can be separately
> bike-shed if we agree on standardizing it. To me, this is much like
> 2-space vs. 4-space indentation. I would use one of them, but I'm happy
> to work on the other when following someone's guidelines (even if it
> means spelling it "centre.") At the moment, I think we have mixed types.
>
>
> Whichever one we pick, I think it would be valuable to note (whether by
> link or short list) the primary differences such as "s" vs. "z," or
> maintaining some spelling originating in French, as well as where to put
> the comma or period when inside a quote, and, of course, the infamous
> Oxford comma. Otherwise, I know *I* will mess it up more than once. :)


*putting on my copyeditor hat*

I strongly disagree with mandating American English vs. British English vs.
any other english in terms of spelling, as one is no more correct than the
other*, and Perl is a language written and contributed to by people from
all over the world. When making edits to an existing document, consistency
may be desirable, but I do not believe we should require even consistency
within a patch with the text that surrounds it. (Plus, "stick with what's
there now" is also the easiest thing to implement.)

Grammar, on the other hand, is much more concrete and we can ensure that it
is correct, for one specific value of correct. Strunk and White's "The
Elements of Style" is a very good reference text, and accessible to the
non-professional-writer, but there are other worthy texts as well.

* As I well understand, being Canadian, and using elements of both American
*and* British English in my lexicon. We mix together our "tire",
"aluminum", "centre" and "colour" with ease!

On Nov 5, 2020, at 2:30 PM, Karen Etheridge <perl@froods.org> wrote:
>
> I strongly disagree with mandating American English vs. British English vs. any other english in terms of spelling, as one is no more correct than the other*, and Perl is a language written and contributed to by people from all over the world. When making edits to an existing document, consistency may be desirable, but I do not believe we should require even consistency within a patch with the text that surrounds it. (Plus, "stick with what's there now" is also the easiest thing to implement.)

I don’t agree that consistency should take a back seat to other style concerns. While I understand and appreciate the direction of international welcome you’re coming from here, I rather doubt that most professionally produced works of technical documentation would intentionally allow a single article to use both “color” and “colour”, for example, outside of quotations.

One of the proposal’s core arguments is that Perl’s core documentation speaks with a single voice. Spelling words inconsistently, especially within a single document, would work against this principle. I don’t think this means denying that every document is the work of many hands — it’s more a matter of making the seams a little more subtle, so that the reader can glide over them effortlessly.

I absolutely agree, on the other hand, that the (as yet still notional) documentation team should enthusiastically welcome all contributions from anywhere in the world, and actively assist these contributors in getting their work into a style that agrees with the rest of the Pod file they’d like to modify or extend — just as any responsible FOSS project would treat any other source-code patch.

I can also understand the objections to standardizing on “American English”, in so many words, as a possible discouragement to contributors outside the United States, and I could offer to downplay how the guide words that. Obviously, it doesn’t meant to imply any declaration of American-English superiority. Since the guide also proposes using CMOS as its “base class”, that bakes in a preference for American spellings anyway.