Proposal: Renaming "Patlet" to "Summary"

[spier]

In our pattern template we have a section called Patlet. We define it as:

Concise 1-2 sentence description of the problem and solution. Readers may quickly review dozens of these patlets to discover and browse the larger library of patterns. http://wiki.c2.com/?PatLet

However many readers find this confusing, as Patlet is no real word in Englisch, and does not have an intuitive meaning. So while the word Patlet is kind of cute, and maybe fun for some of us (hardcore pattern nerds that is :)), it is not very helpful for the average consumer of our patterns.

Therefore I propose to replace the word Patlet by Summary instead.

Here is how I propose to change the definition in the pattern template.

-## Patlet
+## Summary

-Concise 1-2 sentence description of the problem and solution.
-Readers may quickly review dozens of these patlets to discover and browse the larger library of patterns.
-From http://wiki.c2.com/?PatLet
+Concise summary of the pattern.
+Use the first sentence to describe the **problem**, the second sentence to describe the **solution**.
+Readers may quickly review dozens of these summaries to discover and browse our library of patterns.

[spier]

@yuhattor I am curious to get your opinion about this. How did you actually translate the word "Patlet" into Japanese?

[spier]

In terms of costs to implement this, I quickly checked, and outside of the patterns itself, we have not used the word all that much.

Details:

$ ack --ignore-dir=patterns Patlet
meta/boardreports/2021-01.md
39:      - #239, 240 Book work: Shortening some pattern titles to make for nicer links. Adding some Patlets. (@spier)

README.md
89:NOTE: The 'Initial' Patterns below don't have a Patlet yet, which is essential for readers to quickly browse our patterns.

.github/vale/Vocab/ISC_General/accept.txt
1:Patlet

.github/ISSUE_TEMPLATE/pattern-draft.md
17:## Patlet / Summary

.github/lint-pattern-syntax/pattern-template.js
32:          "Patlet": "Patlet",

book/scripts/generate_toc.rb
57:    patlet = extract_section(file, "Patlet")

So to implement this we would have to do two things:

1. go through all existing patterns (and their translations) and replace "Patlet" with "Summary"
2. fix the files listed above, which are mostly scripts used for content validation and book publishing. make them use "Summary" instead of "Patlet"

[yuhattor]

Actually, I have not translated Patlet. The reason is that Title and Patlet are used in a script that generates summaries, and if you translate them into Japanese, the script will not work properly.

I thought about changing the script, but it seemed a bit difficult at the time, so I decided not to do it and to use Title and Patlet as they are.
The Chinese pattern seems to have followed the same way.

I'm definitely in favor of changing PatLet to an easier to understand name like Summary, Description, Abstract, etc 😄 😄 😄

[spier]

@yuhattor quick detour here related to this:

The reason is that Title and Patlet are used in a script that generates summaries, and if you translate them into Japanese, the script will not work properly.

Did you have some ideas for how to implement this different already?

Exploring some below:

1) Use the order of sections

I think we could change the script to "pick the first section as Title, and the 2nd section as Patlet".
That way those sections could have whatever title they like, and would still get picked up correctly to generate the ToC.
The only issue I see with that is that it is rather brittle and also a bit hard to check for maintainers that don't speak the non-English languages.

2) Use a front matter in gitbook

A more stable alternative would be to add some type of jekyll-style front matter to all patter files, so that we can pick up the title + patlet from there, rather than having to parse it out of the markdown. I do remember testing some time back that at least some front matter variables can be used with gitbook, but I am not sure which ones.

3) other ideas?

[yuhattor]

If I misunderstood your question, please let me know, but what I meant that was difficult was not from the technical mattter. At the time I made the first contribution to the book I was complete stranger, and at the time I thought Patlet had a special meaning. So I thought it was a bit difficult to change the name / or propose to change as a stranger.

If you want to change the title, and also the implementation as well, you can just replace all the Patlet with with other words like "Description" or "Summary", and change the below scripts.

InnerSourcePatterns/book/scripts/generate_toc.rb

Lines 55 to 63 in 36e2ca8

	patterns.each do |file|
	title = extract_section(file, "Title")
	patlet = extract_section(file, "Patlet")
	pattern_overview[title] = {
	:file => file,
	:patlet => patlet
	}
	end

[spier]

@yuhattor yeah we had a bit of a misunderstanding here.

What I meant was:
How would you modify the title+patlet extraction logic, if we wanted to built it in a way that the different languages can use whatever title they want for that section?

I am leaning towards option (2) above, even though that would mean that title/description are stored in two places: the respective pattern section and the metadata.

[spier]

I tried the approach with a frontmatter to store the data for title patlet. See screenshot:

So it might work, and even looks quite nice as gitbook as formats the description in a special way.
However a major drawback is that the length of the description field that gitbook provides is limited (notice how the text is cut off).

Also notice the little checkbox icon next to the title.
gitbook allows to add some icons to the title. We could use these to flag the patterns that are more/less mature.
But that's another story and a conversation for another time :)

Based on this little experiment I suggest this approach.

1. Add two frontmatter fields. extract the content of these fields when auto-generating the TOC for the book

---
title: <title goes here>
summary: <text of what used to be called patlet goes here>
---

2. remove the title section from the patterns (as it is now stored in the frontmatter, and just repetition)

3. keep the Patlet text as part of the regular markdown as well (unfortunately this means the text is kept in two place).
   Now this would allow the translators to choose a different section title though i.e. they can rename "Summary" to whatever makes most sense in their language.

4. for the English patterns rename this section to "Summary"