Guidelines for authors: comments

[inactinique]

Here are some suggestions of modifications to the guidelines notebook:

Paragraph three: "In specific instances, the author wants to reveal more of the methodology used behind certain aspects or figures. This is accomplished by placing that information on the hermeneutics layer. Whenever there’s more to explore, the interface indicates to the reader that there’s a connection between the narrative and hermeneutics layer. We will explore later how this can be archived visually. Finally, the readers can jump into the data layer by downloading the raw data (or a subset) and exploring it themselves."

Would be nice to specify that the raw data will be downloadable if legally possible, otherwise it might be a bit frigthening for some authors.

Just after this paragraph, could we put a short video with how narrative and hermeneutics layer are shown by default on the website? A short gif for instance?

Cell tagging

I think all tags should be there in this table (table-1), including 'narrative' and 'hermeneutics' and 'hermeneutics-step' and 'step-x', with a text saying it is explained in details after in the guidelines.

Structuring the Jupyter Notebook

Here, we should precise that the first tagged cells (after the title, contributors, cover, disclaimer, keywords, abstract) should be the "introduction" headline and the following paragraph should belong to the narrative layer. No code or any hermeneutics cell before.

Figures & Tables

The two figures approach and the examples given do not seem coherent. (Figure 1a, figure 1b, but examples with figure 4 and 5 -- might be a problem of the notebook).

Hermeneutics

There seems to be some incoherences into the steps thing.

The table mentins 'hermeneutics-step' but the images shows "hermeneutics step-1". What's the right choice? Or both are right but in that case there should be an explanation of when using which one.

Collapsible headings

Should be more clearly stated that this is for the convenience of the user when she writes the article, but not necessary. In this paragraph, we could also add that "Table of Content (2)" is very convenient too to get a proper writing environment.

Libraries

A link to a more general tutorial on cite2c would be great. anaconda might be well used, or not.

Github

Let's add here that you can ask for a free academic account.

More global comments

I would restructure the guidelines this way:

1. Quickguide
2. Setting up your writing environment 2.1 jupyter installation
   • Install jupyter
   • activate the nbextensions
   • activate the necessary plugin (cite2c)
   • for your convenience: collapsible headings, table of contents (2) 2.2 Zotero account + ask to integrate the JDH group 2.3 Github account
3. Writing: Structuring the Notebook 3.1 Special focus on hermeneutics
4. Submitting
   • submit via a (private or public) repo on github, with two versions of your notebook (anon and non anon), send a mail to jdh.admin@uni.lu when done.

What do you think?

---

edit: 20 july

• We are using english style typography (ie no spaces before ":" or ";").
• Filename conventins: no space in the name, no point but for the extension, no upper case (only lower case), if a date is at the beginning of the name: YYYYMMDD, english quotemarks, etc.

[biumiamy]

I adjusted the notebook in accordance to your comments. Can you take a look at the new version again? However, some last changes might not be in there yet.. http://10.240.4.179/en/guidelines

[inactinique]

Thanks a lot!

A few comments:

• There is (just before the 7th cell of code) a "biography" that should be "bibliography".
• Section 4.1.:
  • Can you add an image quickly showing how to show tags on the jupyter notebooks interface? Tags are not appearing by default, if I remember well.
  • We should explicitly say that what we are tagging are the cells from the first sentence.
• "After the header section, the first title is always introduction and should only contain cells which are part of the narrative (and only in markdown). Cells belonging to the hermeneutics layer and code can follow after the introduction."
  • There can be hermeneutics cells in the introduction. Only the first cell of the introduction (the first paragraph after the title "introduction") has to be "narrative"
• 4.2.: I would add in the table the narrative-steps element

I've seen the discussion around color-coded cell. Haven't tried it yet. I'm quite curious :)

[biumiamy]

thank you for the feedback again! You can check the latest changes by viewing the guideline (https://github.com/C2DH/jdh-notebook/blob/master/examples/Author_Guideline/AuthorGuideline.ipynb) in the preview (http://10.240.4.179/en/notebook-viewer-form)! Sometimes the cache needs some time to update though..

[inactinique]

For now, it's all good. Thanks a lot! Remaining elements, that need to be discussed first:

• the pip install / python3 -m pip install thing (not consistent throughout the guide),
• the coloured cells thing: have tried it yet, but does not work (the documentation is quite scarce on its github's repo and seems to support only a few tags that we do not use).

[biumiamy]

The installation is a general question.... it's already a difference from Mac to Windows, then depending what console you use.. and so on. We need to decide what we want to do here. Or if we always link to outside sources. And yes, for the color-coded cells, that is something we need to adjust. Currently it's not working with the tags I wrote of course.. but I looked in the code a bit, I think it should be easy for Elisabeth or Daniele..

[inactinique]

OK. Let's open a non-urgent specific issue on the installation question and close this one.

[eliselavy]

deploy in version https://github.com/C2DH/journal-of-digital-history/releases/tag/v2.0.2