Contributor Style Guide

[wonderchook]

With the desire from so many people to add content we really need a style guide. This will ensure consistent formatting and voice in LearnOSM.

@MappingKat and @jeffhaack do one of you have time to lead this? Let's put ideas of things it needs to contain in this ticket.

[jeffhaack]

I'd like to take charge of this. I've written most of the guides so far so they're fairly uniform, but with an increasing number of contributors this will be important. Ideas, please post here.

[jeffhaack]

I am devising a style guide for HOT Training Publications. It consists of two sections, one for formatting and one for structuring. I think we should start maintaining the canonical versions of training documents in Markdown, so the formatting will mostly follow the guidelines in the wiki with some added explanation and elements. These elements will be allowed then:

• Title
• Section Heading
• Subheading
• Paragraph
• Numbered List
• Bullet List
• Link
• Image
• Code
• Note (blockquotes in markdown)
• Horizontal Rule
• Table (maybe? - using html)

Then for structure we will have a template structure for tutorials, which will be pretty simple but keep everything in the same style.

I'd also like to work on a translation guide later. If anyone has other ideas let me know.

[maning]

Draft Style Guide we developed during our module sprint: https://hackpad.com/Proposed-Style-Guide-for-LearnOSM-1JJxS8NIQSX

[Nick-Tallguy]

I'm aware that hackpad is disappearing at some point. I've copied all of the text from https://hackpad.com/Proposed-Style-Guide-for-LearnOSM-1JJxS8NIQSX with a view to using this in a style guide

[harry-wood]

So to be clear, the style guide is now part of the learnosm website itself at:

https://learnosm.org/en/contribute/style/ (in github here)

Although it still feels a bit casually pasted in. It fact it says "Paste of data from hackpad" at the top (The hackpad no longer exists). And it's not added to the side navigation. I found it by googling.

The above discussion suggests it was never exactly declared "final and ready to publish", but then I would suggest that's not an appropriate hoop to make ourselves jump through at this point. It was linked to from CONTRIBUTING.md for a few years (then discussion because it disappeared from hackpad). I'd suggest we regard it as "published but obviously never finished", meaning we can close this issue and make new issues for the tidying that needs to happen.

[michael63-osm]

I agree that this needs to be added to the information available from https://learnosm.org/en/contribute/ as mentioned in #651.