[WIP] Stubbing out docs for paper preparation#554
Conversation
|
|
||
| ## Citations | ||
|
|
||
| - Show how to create them. |
There was a problem hiding this comment.
| - How the paper is being produced (Pandoc etc.) | ||
| - How authors can test their submission (what Pandoc command to run) | ||
| - https://gist.github.com/arfon/09a11047de1c972e37f77e95d2c10efa | ||
| - Iterating with Whedon |
There was a problem hiding this comment.
Link to docs here, i.e. point out that authors can ask Whedon to do things too.
| - Show how to create them. | ||
| - Multiple citations inline | ||
| - APA ... | ||
|
|
There was a problem hiding this comment.
Do we need a dedicated section for # Math(s)?
| - Supported types | ||
| - How to link to them (RAW urls for GitHub) | ||
| - Captions | ||
| - Figure placement (good luck!) |
There was a problem hiding this comment.
Flow-control/layout is hard in Markdown but certain commands do work including \newpage
| ## Special cases | ||
|
|
||
| - Multiple authors | ||
| - Corresponding authors |
There was a problem hiding this comment.
i.e. how to denote an author as the corresponding author with a *
|
Good points @arfon! I guess that alongside the docs, an insanely complete example that authors can just delete sections off of would help a lot, i.e: https://gist.github.com/marktheunissen/2979474 ... since in this day and age, fewer and fewer people actually read docs, unfortunately ;) |
|
Yeah, that's a great idea. We could easily update the example paper to be a 'feature complete' one like you suggest. |
| ## Citations | ||
|
|
||
| - Show how to create them. | ||
| - Multiple citations inline |
There was a problem hiding this comment.
let's also talk about style - how to do things like \citet and \citep and what style we want
| - Multiple authors | ||
| - Corresponding authors | ||
|
|
||
| ## FAQ? |
There was a problem hiding this comment.
yes, that we actually update as we get new problems
|
Also (perhaps for a separate PR) it would be nice to include some information about joint submissions between an AAS journal and JOSS. The JOSS blog post announcing this partnership says:
|
👍 great idea. |
|
Hey there @arfon 👋 I saw your pull request after creating my own on adding a TiKZ example to the demo |
5 participants
I'd like to write some better documentation to help authors preparing JOSS papers. For most authors this is a pretty straightforward process, but when it goes wrong, or authors have more specialist needs for their papers, we don't have very good documentation to support them.
I'd be interested to hear from @openjournals/joss-editors what they think we should try and capture here based on their experiences.
/ cc #553