search

quii / learn-go-with-tests

Learn Go with test-driven development
MIT License
22.1k stars 2.8k forks source link

Chapter headings - hard to follow along online #166

Closed tracypholmes closed 4 years ago

tracypholmes commented 5 years ago

When following along online: after the first couple of chapters, you basically get "Write tests.." or "Refactor" headings. It's very hard to tell where you are on the page or get back to a specific section (especially in the bigger chapters) because it all looks the same. (screenshot included).

image

I think this is due to how GitBook uses Markdown to determine chapters, but would you be open to the idea of changing the Level 3 headings to match more of what's in the content, and let the bulk of Write the test/Refactor/etc.. change to Level 4?

I know it's a lot of work, and I definitely don't mind contributing to help out with that.

quii commented 5 years ago

This sounds like a good idea in principle but you're right the effort would be fairly significant and we shouldn't try changing the whole book all at once.

I'm not overly wedded to the particular markdown heading levels (but i think the cadence of the wording important reinforcement) so maybe you could try a PR on a small chapter and we can evaluate it and if it works out well we can just raise separate issues for each chapter and slowly chip away at it all.

What do you think?

tracypholmes commented 5 years ago

That sounds like a plan! I'll raise a PR as soon as I have a bit of free time.

gypsydave5 commented 5 years ago

This is a good idea - the 'cycle' markers shouldn't overwhelm the 'narrative' ;)

wagnerjt commented 5 years ago

Running through the gitbook, I found myself looking at the implementation code and just blindly copying the test code. I believe this was due to not really having context on the problem than just a one sentence overview. My suggestion on the template.

Chapter template

An intro with the following:

Requirement A

The test

The code

The refactor

Repeat above steps for new requirements (i.e. Requirement B)

Wrapping up

An outro with the following:

I can make some edits and do a small PR if there is interest in trying this.

quii commented 5 years ago

This sounds like a great idea!