Rewording, spelling corrections, word mark corrections and more. WIP #170
Conversation
|
@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.
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.
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? |
|
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:
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 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. |
|
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. |
|
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.
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 |
The geometric form of a lozenge appears to be a diamond. The edible lozenge appears in many forms (though my mind went right to Lockets!). "Elongated" seems to be less subject to interpretation, since the more geometrically correct "stadium" is a relatively obscure term.
More losenge than ever before!
These seem to occur all throughout the documentation and are an eldritch nightmare to work around since any rephrasing inevitably breaks the line-width.
|
Thanks for the continued work @Gadgetoid I'll review the current PRs. Line break fixes are welcome.
I like this proposition with the text hyperlinked. It will be something like this rounded rectangular pads |
* Change "lozenge shaped pads" to "rounded rectangular pads" as discussed in microbit-foundation#170 * Add power pads picture to Latest Revision Accessories * Link "rounded rectangular pads" text to the picture where it's not already embedded
* Change "lozenge shaped pads" to "rounded rectangular pads" as discussed in #170 * Add power pads picture to Latest Revision Accessories * Link "rounded rectangular pads" text to the picture where it's not already embedded
TODO
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!