Shorter, more focused referencing guide

[handrews]

This reworks the less-controversial parts of a prevoius attempt (#69) at a referencing guide that was over-ambitious, among other things. It's amazing how being in better health makes my writing less cranky and confrontational! 😅

[lornajane]

Thanks @handrews! I need more time to look at this properly, there are some really great nuggets in here of what doesn't work and why, but I think we might also add some "do it this way" advice and some examples to try to lead people out of the dark place in which they find themselves. Would it be okay for me to add changes directly to this pull request to restructure some of the content?

[handrews]

@lornajane I'd had more content and guidance in a previous iteration of this, and had intended to add more in a later PR. But I'd very much welcome and appreciate collaboration on this. If it's easier for you to edit this PR in place, please go right ahead! I look forward to seeing the changes.

[handrews]

I forgot to add that I put the rendered changes up here:

• https://handrews.github.io/renderings/learn-referencing/referencing/faq.html
• https://handrews.github.io/renderings/learn-referencing/referencing/what.html

[lornajane]

Thanks for being open to some content restructure @handrews - I shifted things out of FAQ format (not considered current practice in documentation, and not an established pattern in these docs) mostly because those articles can get long and difficult to navigate. The content is split into topics, with each page added to the sidebar.

In general, I think paragraphs might be easier to read than bullet points, but I suggest we don't block the pull request for that (I've done enough holding this one up already!).

I would have loved to have seen at least one or two examples in the text, I think that's something that the learn site can excel at - but we can add them later, maybe after hearing user feedback.

[handrews]

@lornajane thanks! I will look at this in detail soon. Just to respond to a few comments first:

shifted things out of FAQ format (not considered current practice in documentation

Great! I'm not up on current best practices and was not attached to a FAQ format at all.

In general, I think paragraphs might be easier to read than bullet points

I've been told "bullet points, not paragraphs!" over and over by people who outright refuse to read anything I write in prose because I'm too wordy. I'm happy for anyone else to restructure it, I'm just hyper-sensitive at this point.

I would have loved to have seen at least one or two examples in the text

I am horrible at examples. I learn theory-first, unless the theory just isn't articulated and I have to construct it from examples. Most people learn examples-first. I've never understood how to connect with that, so hopefully others will fill them in. I'm happy to provide a topic list or feedback, though.

[lornajane]

Let's leave the bullet points and not worry too much about the examples. They can be fleshed out over time - I do think they're useful, but let's add them as we see them in the wild or something!

[lornajane]

@handrews I think this is an improvement and we should merge if you're happy enough to let this version go as-is.