search

microbit-foundation / dev-docs

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

Doc consistency #175

Closed Gadgetoid closed 4 years ago

Gadgetoid commented 4 years ago

❗ This changeset depends upon merging #174. The diff will be very big and noisy until #174 is merged.

This PR, #174 and others to follow aim to replace the mess in #170 with a series of documented commits that correct linebreaks, markdown consistency, spelling and - finally - rephrasing, in turn.

This changeset enforces some style rules in the name of consistency:

These "rules" are somewhat arbitrary, but informed by the HTML rendered to the website and for ease of reading/editing.

There are no typo fixes or re-wording in this PR- I will do a pass on typos once this and #174 are merged.

Titles

Pages without a lead-in title look weird, examples - https://tech.microbit.org/latest-revision/announcement/ and https://tech.microbit.org/bluetooth/apps-and-examples/ - since the top-margin is not equal to the left/right margins.

Since the page template steals the H1 tag, titles should ideally start at ## Title which is H2. That said- the semantic meaning of H tags has been somewhat lost in the noise of the web. Pages seemed to start with/use one or the other, so I've erred on the side of technically correct and used H2+.

I have replaced some **strong** titles with #### H4 titles without knowing if the site will correctly generate this markup. However I have confirmed that <h4> does have appropriate CSS to be used in these cases- fingers crossed!

Lists of links

Lists of links that are not bulleted tend to parse as sentences/paragraphs rather than individual, unrelated units. Adding bullets makes them clearly, intentional lists. Contrast the following:

image

To before:

image

Additionally, lists of links have been moved up the heading (and TOC-tree) heirachy to H2 and titled "Further information" (though this could be "More information" or otherwise) to clarify in the TOC exactly what type of links they are.

Gadgetoid commented 4 years ago

Rebased! I don't know what happened there, but it should be good to go now.

I've made some educated assumptions about how my changes will affect the actual website- is there any way I can build the website locally to check I haven't broken anything?

microbit-mark commented 4 years ago

Thanks @Gadgetoid . I've given this a cursory review and looks good. I've also built it locally and can't see anything broken. let's merge and build to see if there are any issues in CI. I'll post a preview here when done.

The developer site is closed source at present, so their isn't a way to build locally outside The Foundation

microbit-mark commented 4 years ago

Should eventually build at doc-consistency.review.tech.microbit.org.s3-website-eu-west-1.amazonaws.com

Looks good to me as far as the content goes @Gadgetoid. What do you think?

Gadgetoid commented 4 years ago

I haven't spotted any eggegious errors or breakage.

I'm already seeing things I want to fix 😆

Chiefly:

  1. Overview appearing in TOC tree
  2. Some longer pages without a TOC
  3. No title/padding above images on hardware pages
  4. The template on /software/other-languages/ probably needs put in backticks- if we can backtick backticks... or linked out somewhere. This page is a bit confusing!