search

microbit-foundation / dev-docs

The content of the tech.microbit.org site
https://tech.microbit.org
Other
56 stars 70 forks source link

Rewording, spelling corrections, word mark corrections and more. WIP #170

Open Gadgetoid opened 4 years ago

Gadgetoid commented 4 years ago

TODO

  1. [x] Line endings - see #174
  2. [x] Consistency - see #175 (depends on #174)
  3. [x] Typos
  4. [ ] Re-phrasing
    1. [x] The Great Lozenge Adventure
    2. [ ] Port everything from this PR into a single commit or series of rationalised, clean commits
  5. [ ] Fixes and tweaks
    1. [ ] Overview links appearing in TOC tree
    2. [ ] Some longer pages without a TOC (which??)
    3. [ ] No title/padding above images on hardware pages
    4. [ ] Review /software/other-languages/ - this page is a bit confusing!

Original Post

As I get up to speed with the docs, I keep bumping into clumsy phrasing (subjective to a degree) and small errors. Rather than suggesting these one at a time via code comments I've forked dev-docs and collated them.

Due to the sheer number and extent of changes here, it might be wise to take these as suggestions rather than as a single PR I think you should merge. I am also, of course, open to suggestions about how to proceed.

In some cases I have leant upon my experience with MicroPython/MakeCode to reword technical parts of the documentation for clarity. I am, however, not a micro:bit expert and may have introduced technical errors.

TLDR: I am raising this a draft for visibility and discussion.

Note: This documentation references https://github.com/microbit-foundation/universal-hex/, which is currently 404'ing for me. (Found an "email us" link in the new V2 announcement doc, but this isn't present in the universal-hex doc)

Note2: I'm probably going to lose my fight with "lozenge", but since it's vague in terms of edible sweets and incorrect in terms of geometry I still venture they should be called "elongated pads." Sorry!

microbit-mark commented 4 years ago

@Gadgetoid Firstly this is a very welcome contribution. Thanks for taking the time to review the docs. Much of this was written to support developers around the first iteration of the micro:bit, so it's great to have more eyes on it and clear things up for V2.

On cursory review, I think everything you have edited here makes the documentation clearer, so I think it's worth making this a ready PR if you are happy to do that.

Note: This documentation references https://github.com/microbit-foundation/universal-hex/, which is currently 404'ing for me. (Found an "email us" link in the new V2 announcement doc, but this isn't present in the universal-hex doc)

We're in the process of open-sourcing much of our work, so this should be okay but perhaps we should copy the "email us" link to the universal hex page whilst we make the repo open.

Note2: I'm probably going to lose my fight with "lozenge", but since it's vague in terms of edible sweets and incorrect in terms of geometry I still venture they should be called "elongated pads." Sorry!

I don't feel strongly about this, but I think you might be right. Losenge/lozenge feels like something 3D. "Elongated pads" perhaps doesn't clarify the shape. Does "oblong pads" work? The dev docs is really the only place we refer to them. @jaustin any preference here?

Gadgetoid commented 4 years ago

You're welcome!

I don't mind upgrading into a full PR when it's ready. I think there's more that could be done, this was mostly as a casual pass over the docs as I read and tried to internalise them. I was starting to pick up on a few key aspects that I think increase readability:

  1. Drop unecessary intensifiers
  2. Split long sentences
  3. Try to standardise technical terminology and actions ("connecting a usb power cable" vs "inserting a usb power lead", "data sheets" to "datasheets" and so on)
  4. Splitting lists of equally important links or notes into bullets
  5. Personal bug bears like "as well as" in lieu of "and" and "in addition to"

One big tooth I haven't pulled yet is fixing the pervasive use of line-breaks to wrap text to some imaginary boundary. I'm assuming this is a legacy holdover from docs being originally written by someone technical in something like vim. It's an easy fix, but creates lots of spurious "changes" where, in fact, nothing of substance has changed. Fixing this will make the docs easier for a casual passerby to edit without feeling they have to manually correct line wrapping.

Most of the spelling corrections were caught once I started pasting the entire document into VSCode (I was using the web editor).

My geometry argument was predicated on a "lozenge" being known more like this - https://mathworld.wolfram.com/Lozenge.html

This was a rabbit hole I fell down when I saw "losenge" and wasn't sure about spelling.

jaustin commented 4 years ago

Thanks @Gadgetoid!

Actually, very few people know what we mean by 'lozenges' (likely for the geometry-related reasons you mention), and why they're called that is kinda lost in the mists of BBC time. I think we can consider renaming them and just be clear in the page that they were previously called "the lozenges". I'm not sure Stadia will be any clearer, though 😅. "Elongated pads" could be mistaken for aspects of the edge connector, so open to other suggestions. "Rounded rectangular pads"?

For the line endings, I'm not precious about it personally, but @microbit-mark works on the repo more than most people so think it should be his call. If we do it, I'd like to make a single PR that only does line endings, nothing else and merge that separately. Ideally a single commit to keep the history clean.

Gadgetoid commented 4 years ago

Drat, I wish I'd read this before I went through and did a more thorough purge of line endings and other issues.

The commits and diff produced by this draft PR will serve as a reference to go through and produce a cleaner set of commits that address the following in turn:

SNIP! see first post.

Would be a bit of effort, but might be worth it if you're keen to keep a clean commit history. My commit messages aren't exactly insightful edit: this was a better use of my time than Twitter rants.

You're right regarding "elongated pads" being very easy to confuse with the edge connector.

"Rounded rectangular pads" is certainly very descriptive. I wonder if that could be further clarified by consistently linking to a reference image: https://tech.microbit.org/docs/accessories/assets/making-accessories-d7c25.png

And, maybe "rounded-rectangle pads" is more concise, I'm not sure? Or even "round-rectangle pads."

The form "Rounded-rectangle pads (picture)" might work.

microbit-mark commented 4 years ago

Thanks for the continued work @Gadgetoid I'll review the current PRs. Line break fixes are welcome.

"Rounded rectangular pads" is certainly very descriptive. I wonder if that could be further clarified by consistently linking to a reference image: https://tech.microbit.org/docs/accessories/assets/making-accessories-d7c25.png

I like this proposition with the text hyperlinked. It will be something like this rounded rectangular pads