New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update index.md #6933

Merged
merged 4 commits into from Apr 18, 2018

Conversation

Projects
None yet
6 participants
@Awjin
Contributor

Awjin commented Apr 17, 2018

Hello 馃憢

This is my first time contributing to the docs repo. I made quite a few changes here, but the overall goal was to help simplify the text. Jekyll is one of my favorite tools, so I'd love to help make it even more accessible!

Awjin added some commits Apr 17, 2018

Update index.md
Convert intro to bullet pts, and help simplify the text

@DirtyF DirtyF requested a review from jekyll/documentation Apr 17, 2018

@kacperduras

Imo, looks ok :)

@coliff

To be honest, I didn't find that most these changes were helpful or made the page any more readable. I prefer how it was before.

I do think the line:

Be aware of these messages if you wish to avoid certain death.

Could be better though - so changing it to 'Common pitfalls to avoid.' is an improvement 馃憤

@chrisfinazzo

Welcome @Awjin, good to have you here.

While I don't mind most of the changes, I think I'm with @coliff when it comes to concerns about readability. Swapping out the intro 'graph' for a bulleted list (where people then have to read individual items) doesn't feel right.

It becomes, "read item, stop, read item, stop, etc." and disrupts the flow of the text.

- Getting your site up and running
- Creating and managing your content
- Customizing how your site works and looks
- Deploying to various environments

This comment has been minimized.

@chrisfinazzo

chrisfinazzo Apr 17, 2018

Contributor

Used in this context, "various" is a 'weasel word'. Perhaps this line could be simply, "Deploying your site."

This comment has been minimized.

@Awjin

Awjin Apr 17, 2018

Contributor

That was copy/pasted from the original, but I agree.

RE: your concern about flow--good point. What do you think about something like this?

We鈥檒l cover topics such as getting your site up and running, creating and managing content, customizing your build, and deploying.

@Awjin

This comment has been minimized.

Contributor

Awjin commented Apr 17, 2018

Thanks for the reviews everyone.

@coliff : How do you feel about the other "tooltip" sections? A lot of them had redundant descriptions that I deleted.

@chrisfinazzo : Points well taken, I added an inline comment

Also, I'm realizing it would've been better to split these edits into separate commits with my rationale as commit messages. I'll do that next time.

a converter (like [Markdown](https://daringfireball.net/projects/markdown/))
and our [Liquid](https://shopify.github.io/liquid/) renderer, and
spits out a complete, ready-to-publish static website suitable
for serving with your favorite web server. Jekyll also happens to be the engine

This comment has been minimized.

@Awjin

Awjin Apr 17, 2018

Contributor

I feel like this explanation makes total sense to someone who uses Jekyll, but to a newcomer it might feel dense. There's a lot of moving parts, with no room between the commas for the weight of each part to sink in. Thoughts?

- Customizing how your site works and looks
- Deploying to various environments
- Participating in the development of Jekyll
This site is a comprehensive guide to Jekyll. We鈥檒l cover topics such as getting your site up and running, creating and managing content, customizing your build, and deploying.

This comment has been minimized.

@chrisfinazzo

chrisfinazzo Apr 18, 2018

Contributor

"...aims to be a comprehensive guide to Jekyll." I think the current "Docs" homepage used this phrasing as well.

Let's not get ahead of ourselves here 馃槈

@chrisfinazzo

Looks good, save for 1 small change I noted.

@chrisfinazzo

This comment has been minimized.

Contributor

chrisfinazzo commented Apr 18, 2018

Also, I'm realizing it would've been better to split these edits into separate commits with my rationale as commit messages. I'll do that next time.

From a review standpoint, it's not a big deal, although it should make integration easier if it ever becomes necessary to do any git squash sorcery.

@DirtyF

DirtyF approved these changes Apr 18, 2018

@DirtyF

This comment has been minimized.

Member

DirtyF commented Apr 18, 2018

@jekyllbot: merge +docs

@jekyllbot jekyllbot merged commit 24df53b into jekyll:master Apr 18, 2018

3 checks passed

WIP ready for review
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment