feat: introduce first three exercises #1
Conversation
leoriviera
left a comment
leoriviera
left a comment
There was a problem hiding this comment.
I've left some comments. These are just a first pass, and I'd be happy to discuss anything with you @hevansDev. Good job thus far.
|
|
||
| Exercises and slides for "How to write and publish your first blog post" workshop | ||
|
|
||
| You can find the slides for the workshop [here](https://docs.google.com/presentation/d/1KQn6lWmDmaEXEXBLMoaNCotnFaoaDj7uLz7sgoXQ3-g/edit?usp=sharing). |
There was a problem hiding this comment.
Do you want to do the slides via Google Slides, or would you rather define slides with Markdown alongside the content?
There was a problem hiding this comment.
Markdown slides would be cool, do you have a preferred option for that?
There was a problem hiding this comment.
There's a few out there. sli.dev looks good! Unfortunately, just like JavaScript frameworks, you don't really know until you try.
| - Why Write Blogs | ||
| - Choosing what to Write | ||
| - [5 minute exercise: come up with an idea for a blog](./exercises/excercise-1.md) | ||
| - The Writing Process: The First Draft | ||
| - [15 minute exercise: create an outline for a blog](./exercises/excercise-2.md) | ||
| - The Writing Process: Editing and Review | ||
| - Sharing Your Work | ||
| - [30 minute exercise: raise a pull request and publish your outline](./exercises/excercise-3.md) | ||
| - Next Steps | ||
| - Challenges: | ||
| 1. [Finish your blog](./challenges/challenge-1.md) | ||
| 2. [Create your own blog site with GH pages](./challenges/challenge-2.md) |
There was a problem hiding this comment.
Decide on whether you're using title case or not. Given this functions as a table of contents, I would lean towards title case.
Depending on how you're publishing this, I'd use tools which generate a table of content to avoid manually updating this when you add more content.
|
|
||
| ## Resources | ||
|
|
||
| - Book: [Writing for Developers](https://github.com/scynthiadunlop/WritingForDevelopersBook?tab=readme-ov-file) By [Piotr Sarna](https://bio.sarna.dev/) & [Cynthia Dunlop](https://github.com/scynthiadunlop) |
There was a problem hiding this comment.
Book title is enough, and fewer links are better. You don't need to link to the authors' personal websites or GitHub profiles, given those are subject to change.
Writing for Developers is a broad topic, and there are many books on the subject. I'd say you should include the full title of the book, Writing for Developers: Blogs That Get Read, so it's clear it's relevant.
I would link to it from the publisher's website, as opposed to the GitHub repo. Manning's Livebook interface provides a better reading experience than a collection of Markdown files.
I would also italicise the book title.
| - Book: [Writing for Developers](https://github.com/scynthiadunlop/WritingForDevelopersBook?tab=readme-ov-file) By [Piotr Sarna](https://bio.sarna.dev/) & [Cynthia Dunlop](https://github.com/scynthiadunlop) | |
| - *[Writing for Developers: Blogs That Get Read](https://www.manning.com/books/writing-for-developers)* book |
|
|
||
| - Book: [Writing for Developers](https://github.com/scynthiadunlop/WritingForDevelopersBook?tab=readme-ov-file) By [Piotr Sarna](https://bio.sarna.dev/) & [Cynthia Dunlop](https://github.com/scynthiadunlop) | ||
|
|
||
| Contributions, suggestions, corrections, and additions welcome - please raise an issue or open a PR. No newline at end of file |
There was a problem hiding this comment.
These are two separate thoughts, and should be two separate sentences. The dash fulfils no function here.
| Contributions, suggestions, corrections, and additions welcome - please raise an issue or open a PR. | |
| Contributions, suggestions, corrections, and additions welcome. Please raise an issue or open a PR. |
Given this project is focussed on writing and you're actively soliciting contributions, it might be worth specifying a style guide to stick to such that there's consistent decisions made on writing and formatting.
| @@ -0,0 +1 @@ | |||
| # Challenge 1: Finish your blog No newline at end of file | |||
There was a problem hiding this comment.
This is a title. It should be cased appropriately.
| # Challenge 1: Finish your blog | |
| # Challenge 1: Finish your Blog |
There was a problem hiding this comment.
It might be useful to clarify what "blog" means in this context.
|
|
||
| 4. Create a new Markdown (.md) file in the `_posts` directory with today's date and the title of your blog, for example: `2025-04-15-Not-Another-Update.md` `yyyy-mm-dd-your-blog-title.md`. | ||
|
|
||
| 5. Copy your outline from [exercise 2](../exercises/excercise-2.md) into your newly created file. |
There was a problem hiding this comment.
| 5. Copy your outline from [exercise 2](../exercises/excercise-2.md) into your newly created file. | |
| 5. Copy your outline from [Exercise 2](../exercises/excercise-2.md) into your newly created file. |
There was a problem hiding this comment.
I think the prose in this exercise needs an extensive rework to be more approachable.
leoriviera
left a comment
leoriviera
left a comment
There was a problem hiding this comment.
I've left some comments. These are just a first pass, and I'd be happy to discuss anything with you @hevansDev. Good job thus far.
As you've asked for my feedback on these exercises, I've raised a PR so I can make use of GitHub's review features.