Writing style guide: we need one
mrchristian opened this issue · 16 comments
OSMOOC should have a page for writing a writing style guide. It could be that the project uses an existing one, like Chicago, and then lists variations like mixing US and UK spellings.
Extra guidance can be given on styles, for example like using not using bold for emphasis. Nielsen guides on good on web styles.
Nielsen, Jakob. 1997. ‘How Users Read on the Web’. Nielsen Norman Group (blog). 1 October 1997. https://www.nngroup.com/articles/how-users-read-on-the-web/.
‘Writing Digital Copy for Domain Experts’. n.d. Nielsen Norman Group. Accessed 17 November 2017. https://www.nngroup.com/articles/writing-domain-experts/.
There will also be preferences of terms and acronyms.
Consider those for whom English is a second language, too.
https://meta.wikimedia.org/wiki/Writing_clearly
Hi @mrchristian, did we ever decide on writing something like this in the end? We've got a loooot of text now for 2 modules, so guess this could still come in handy.
We haven't nailed this down yet. The best thing to for style guides is to incrementally build them. The reason is that you need to mold a guide to the content and context. So let me start one with some basics in it and then we can expand. I will make a start document tomorrow.
A related question here, should we use - [ ] and - [x]for checkbox list, it will look nice on github, but not on regular markdown...
- no
- yes
A related question here, should we use
- [ ]and- [x]for checkbox list, it will look nice on github, but not on regular markdown...
- no
- yes
Yep, see here @jcolomb! https://github.com/OpenScienceMOOC/Module-5-Open-Research-Software-and-Open-Source/blob/master/content_development/Task_1.md#checklist-for-launching-your-project-
@Protohedgehog I am quite sure the pandoc conversion will give an awful html, no idea what the python notebook will do (no linux here...) I would vote for going back in the master to the version before the pull request was accepted and discuss/test it a bit more before choosing a way to do checklists.
It does give some pretty weird stuff, take a look at the files in Atom. I actually use the version integrated into RStudio. But, check what it looks like in Eliademy: https://eliademy.com/app/a/courses/02d7338a7e - this is simply a copy and paste job of the HTML!
You can open the Jupyter notebook in your browser - click the link which says view here: https://github.com/OpenScienceMOOC/Module-5-Open-Research-Software-and-Open-Source/tree/master/content_development#in-ipython-notebook-format
looks also bad on Eliademy, should we just abandon the - [ ] ? and use a special character?
Ah yeah, I see. Maybe I could just replace them with ticks for now? @jcolomb
one can use
▢ which gives the special character: (copy paste also work :) )
▢
there are others: (https://www.alt-codes.net/square-symbols)
❏
▣
Let's decide for one and write a writing style guide file: in the main repo? (is there already one?)
I think @mrchristian was taking the lead on this one. Not sure if something has been prepped already?
seems nothing was don on any of the mooc repos, yet
I started a (empty) document, please check whether that would be the right place, and let's start populating it with content !
https://github.com/OpenScienceMOOC/Main/compare/master...jcolomb-writingstyle?quick_pull=1
Yeah, it's perfect for now. Danke!!
Then I open an issue in the main and close this one!