Improve collections docs #5691

tomjoht · 2016-12-26T04:34:30Z

See #5630 for more details on the update.

@jekyll/documentation

@DirtyF

See #5630 for more details on the update. @jekyll/documentation @DirtyF

ashmaroli

not very sure why you changed e.g. to for example. Seems like just a personal preference.
But there are some other suggestions you may have to consider

ashmaroli · 2016-12-26T11:58:29Z

docs/_docs/collections.md

@@ -7,12 +7,18 @@ permalink: /docs/collections/
 Not everything is a post or a page. Maybe you want to document the various
 methods in your open source project, members of a team, or talks at a
 conference. Collections allow you to define a new type of document that behave
-like Pages or Posts do normally, but also have their own unique properties and
+like Pages or Posts do normally but which also have their own unique properties and


IMO, this change is wrong..

Collections allow you to define a new type of document that behave like Pages or Posts do normally but which also have their own unique properties..

just doesn't flow well..

okay, changed it back.

ashmaroli · 2016-12-26T12:06:05Z

docs/_docs/collections.md

 documents. YAML Front Matter is read in as data if it exists, and everything
-after it is stuck in the Document's `content` attribute. If no YAML Front
+after it is available in the document's `content` attribute. If no YAML Front


- after it is available in the document's `content` attribute. + after it, is accessible via the document's `content` attribute. (e.g. `{{ post.content }}`)

ashmaroli · 2016-12-26T12:08:36Z

docs/_docs/collections.md

 ## Liquid Attributes

 ### Collections

-Each collection is accessible via the `site` Liquid variable. For example, if
+Each collection is accessible through the `site` variable. For example, if


👎 on changing via to through

"via" and "e.g." and other Latinates are discouraged in technical style guides (such as the Microsoft Manual of Style). They may be familiar in the U.S., but for non-native speakers in other countries reading English, Latinates introduce more complexity. of course it's somewhat trivial here. seems like both are equally readable.

I'm fine with either. Latinates will be very understandable to folks who speak Latin-derived languages, but may prove a barrier for many others. Perhaps removing this sentence altogether and replacing it with:

Each collection is accessible as a field on the site Liquid variable.

i don't mean to cause fuss over a point that matters so little. the benefit of latin abbreviations is that they do save space, and developers like things as brief as possible usually.

Made minor grammar updates

tomjoht · 2016-12-27T03:48:54Z

I made the requested updates. Submitting for re-review.

ashmaroli · 2016-12-27T03:51:31Z

docs/_docs/collections.md

@@ -51,7 +51,7 @@ defaults:

 Create a corresponding folder (for example, `<source>/_my_collection`) and add
 documents. YAML Front Matter is read in as data if it exists, and everything
-after it is available in the document's `content` attribute. If no YAML Front
+after it is accessible via the document's `content` attribute. If no YAML Front


i had also suggested a comma following "after it": after it, is accessible

putting a comma between a noun ("everything") and a verb ("is") would make this grammatically incorrect. https://www.grammarly.com/handbook/punctuation/comma/4/comma-with-subjects-and-verbs/

I don't want to continue arguing over this.. just one last attempt..
Read through the following:

"Everything after it is available online" — this denotes a point-in-time after something is available online. (the noun is just Everything)
"Everything after it, is available online" — this denotes a point-in-time right now and beyond. (the noun is Everything after it referring to whatever there is, after the object it. (it == FrontMatter dashes in our original context.)

Upvote if I'm in the right, else downvote. 😃

sorry, i just don't see the logic there. if you were omitting words, then the comma could work. Such as, "YAML Front Matter is read in as data if it exists, and everything
after, in the Document's content attribute." In that case, the "," stands for "is read in as."

There is also a slight pause in your phrasing, so I can see why you might wan 8000 t a comma there to indicate the pause.

I think the overall sentence is a little janky anyway. The problem is that "it" is ambiguous (does it refer to Front Matter or data -- at first read, it's not all that clear), and there are 2 "it" references.

Here's how I would fix that:

Create a corresponding folder (e.g. <source>/_my_collection) and add
documents. YAML front matter is processed if the front matter exists, and everything
after the front matter is pushed into the Document's content attribute. If no YAML Front
Matter is provided, Jekyll will not generate the file in your collection.

I think "read in as data" is kind of vague, and "is stuck into" is also an odd word choice. Do you like this new paragraph better, or should I keep it as is?

I don't mean to bikeshed this point. Probably doesn't matter a whole lot either way. I'll commit this update and you can downvote it if you hate it.

see how many times you repeated front matter..? it was used as a ~~preposition~~ pronoun for the same front matter.

I only repeated it to avoid the ambiguity. Feel free to change this sentence to make it read how you think it sounds best. I'm actually heading out of town for a few days, so my communication will be spotty. (I didn't want to bring up capitalization issues with Front Matter versus front matter, or document versus Document, but I'll try to include something in a style guide at some future point so we maintain consistency.)

parkr

Thanks again! Just a few comments here.

parkr · 2016-12-29T05:59:18Z

docs/_docs/collections.md

+collections:
+  my_collection:
+    output: true
+    permalink: /awesome/:path/:title.output_ext


:title.:output_ext here – there is a colon missing between the . and the o.

parkr · 2016-12-29T06:02:03Z

docs/_docs/collections.md

 ## Liquid Attributes

 ### Collections

-Each collection is accessible via the `site` Liquid variable. For example, if
+Each collection is accessible through the `site` variable. For example, if


I'm fine with either. Latinates will be very understandable to folks who speak Latin-derived languages, but may prove a barrier for many others. Perhaps removing this sentence altogether and replacing it with:

Each collection is accessible as a field on the site Liquid variable.

tomjoht · 2016-12-29T08:29:53Z

I made the updates here.

tomjoht · 2017-01-15T06:03:26Z

Just checking, are you waiting on me for anything related to this PR? I'd like to see all my PRs either get merged or closed, rather than go stale.

ashmaroli · 2017-01-15T06:09:31Z

/cc @parkr

parkr · 2017-01-17T02:38:55Z

@jekyllbot: merge +site

Improve collections docs

f5eb869

See #5630 for more details on the update. @jekyll/documentation @DirtyF

jekyllbot assigned DirtyF and parkr Dec 26, 2016

ashmaroli requested changes Dec 26, 2016

View reviewed changes

Made requested updates on this topic

6c5f6ce

Made minor grammar updates

ashmaroli reviewed Dec 27, 2016

View reviewed changes

parkr requested changes Dec 29, 2016

View reviewed changes

made requested updates

caf5c00

fixing sentence in dispute

c8ef313

DirtyF approved these changes Jan 8, 2017

View reviewed changes

DirtyF mentioned this pull request Jan 8, 2017

Fix broken links in documentation #5736

Merged

jekyllbot merged commit 16d71b1 into jekyll:master Jan 17, 2017

jekyllbot added the documentation label Jan 17, 2017

jekyllbot added a commit that referenced this pull request Jan 17, 2017

Update history to reflect merge of #5691 [ci skip]

67ab159

jekyll locked and limited conversation to collaborators Jul 11, 2019

jekyllbot added the frozen-due-to-age label Jul 11, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve collections docs #5691

Improve collections docs #5691

Improve collections docs #5691

Improve collections docs #5691

Conversation

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment