Comments on Best Practices article template

[jchodera]

I love the eLife template that you're starting with.

Here are some suggestions that may make it better for our purposes:

• A nice custom checklist panel environment would make it a lot easier for authors to come up with something that is usable and has a consistent style. Perhaps the appendix box environment could be adapted for this purpose?
• For the Best Practices papers, it probably makes sense to use more of the page width for body text and checklists.
• I have a stylistic preference for sans serif math fonts to go along with the sans serif text.
• The date, version, and DOI should probably appear in the left column on the first page.
• The template can be restructured to give a better example of what we hope the Best Practices papers to look like:
  • The Abstract might have specific subsections that describe the intended audience, specific application domains, and scope of the document to make it easier for readers to find Best Practices of relevance to them.
  • An Introduction might follow the Abstract, clarifying the scope and highlighting some recent applications to give the readers a better idea of whether this is the document they want
  • The Checklist might come next
  • The Detailed Best Practices section that elaborates on the decisions recommended by the Checklist may come next
  • A Discussion at the end may highlight still-under-debate areas (though maybe we want a specific section for this?), as well as areas for improvement or things that would help focus areas the next revision can improve

[davidlmobley]

I think these are in general good ideas; I especially like the points about restructuring the template along the lines of what we hope these might look like, or think they might often look like.

[mrshirts]

Thanks for the detailed input! I am having a hard time visualizing what you mean by "nice custom checklist panel environment". Can you link to an example, perhaps?

I agree on restructuring the template to be in the form we want. Other formatting things we can definitely look at (that's where we probably could use a LaTeX consultant once we have enough formatting ideas!)

[jchodera]

Thanks for the detailed input! I am having a hard time visualizing what you mean by "nice custom checklist panel environment". Can you link to an example, perhaps?

I think we want something that generates visually appealing checklist-like panels while making it as easy as possible from the author perspective to slot in the content they want: checklist section groupings, checklist items with boldfaced step summaries, descriptions, and references to other sections of the paper that describe best practices in more details.

As far as visual appearance, you can find some examples that are marginally appealing here:

• Checklist with sections and boldfaced step summaries (but awful font choices otherwise) (link no longer leads to a checklist)
• Minimalist checklist with sections
• Minimalist checklist with sections in boxes
• A visually appealing checklist
• Ducati maintenance checklist

[davidlmobley]

I like the first one on John's list a lot, though there are a couple of these that work for me. Basically we want somethign that does checklists which can (but don't have to) be grouped into sections, and each item could have a boldface summary or be just plain text and might or might not span multiple lines.

(Link to the first one above has been changed, but here is a screencapture of what was there.)

[mrshirts]

Got it! It was unclear to me earlier if was a checklist for the authors, or a checklist that the authors were preparing for the readers as the "checklist" part of the best practices documents. You are referring to the latter.

[dmzuckerman]

Regarding conflicts, should we assume they must be financial? We could change the default subheading 'Competing Financial Interests' to 'Potentially Competing Interests' and ask for financial and other interests. For example, 'DMZ is a developer of the WESTPA software package,' which might bias me to present WE and WESTPA the benefit of the doubt. Probably not a big deal, but it would be nice to set a high ethical standard.

[davidlmobley]

Great idea, yes, I'll add this to my list in #20 . (Added)

[dmzuckerman]

We want to steer reader comments to the github repo. There should probably be info about that on the front page and the end. On the front page, below corresponding authors (which we should retain, so folks get academic credit) we can put a note for readers to comment directly on the github repo. Then we can also say the same in a subsection at the end, perhaps just above Author Contrib, to emphasize its importance.

[justinGilmer]

@dmzuckerman Something that PLOS does well is on the side panel when viewing an article, it provides tweets that reference the paper. We could possibly have a conversations tab on the side of the article that shows the github issues.

This seems to be very similar to what we are looking for. Although I am quite unfamiliar with Jekyll and implementing this API.

[dmzuckerman]

Good idea! I'm not a good person to comment on feasibility.

…

________________________________ From: Justin Gilmer [notifications@github.com] Sent: Wednesday, September 20, 2017 10:12 AM To: livecomsjournal/article_templates Cc: Daniel Zuckerman; Mention Subject: Re: [livecomsjournal/article_templates] Comments on Best Practices article template (#16) @dmzuckerman<https://github.com/dmzuckerman> Something that PLOS does well is on the side panel when viewing an article, it provides tweets that reference the paper. We could possibly have a conversations tab on the side of the article that shows the github issues. This<http://donw.io/post/github-comments/> seems to be very similar to what we are looking for. Although I am quite unfamiliar with Jekyll and implementing this API. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#16 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/AUWz1_TOKiwt8811DAsTaChx9OxM4kz4ks5skUdmgaJpZM4PP39l>.

[davidlmobley]

@justinGilmer - you're having some good ideas. I think we want to be careful to distinguish between two different things in discussions for clarity though:

• actual journal website (livecomsjournal.org)
• journal information site (https://livecomsjournal.github.io/)
  (Maybe we need names for these to improve clarity?)

Anyway, I THINK you're asking about the actual journal website, which is actually run on Scholastica and where we have very little control over design/features at this point (though hopefully that'll improve in the future). The journal information site runs Jekyll, and we have a bit more freedom doing things there (though it's still hard to be super fancy).

@ptmerz will need to comment on Jekyll feasability I think. :)

[ptmerz]

I would have to look into Jekyll feasibility, I don't know offhand, but I also think that what @justinGilmer refers to would be about the journal page (livecomsjournal.org). So we would need to ask Scholastica about feasibility.

For the info page (livecomsjournal.github.io), I am not sure commenting features are necessary, as these pages should be relatively static once we worked out the policy details.

[justinGilmer]

@davidlmobley You are totally correct, I definitely had it mixed up!

I guess that also raises the question: Do we have a place to discuss the journal website itself? If so, I have definitely missed that.

[davidlmobley]

@justinGilmer - the journal website content is all on this site: https://github.com/livecomsjournal/journal_information
Michael migrates it by hand from there to the actual live page.

So that would probably be the best place to discuss. Maybe you can start an issue tracking things we should discuss with Scholastica that we'd like them to enable if possible or at least give us freedom to modify. As I understand it hosting is in beta and they will be adding lots of features, etc. eventually, so we should get them feedback/requests.

[hmayes]

A couple stylist comments:
--Quite minor: On page 6, why is the spacing different between the lines?
--Re the gutter: do we imagine a use for it beyond on the first page where it specifies the contact info, etc.? Annual Reviews uses gutters for figure captions, first defining acronyms, other definitions, etc. If we want to use the gutter space in that way, let's add some examples. Otherwise, let's use the whole page (helps with tables and images) and go to two-column.

[mrshirts]

Good comments on gutter. We could get rid of it after the first page. Using the gutter for other things (figure captions, etc), could complicated this a fair amount, and we don't want to have to resolve people's typesetting issues. Perhaps the stuff in the gutter should just be at the bottom of the page.

No idea on the space difference between the lines, but I could ask.

[hmayes]

Agreed. I like RSC journals' approach of a gutter next to the abstract, then removing it and switching to two-columns. I've found their LaTex templates easy to use.

I'm probably the only one who would notice spacing differences between those lines; not a big deal.

[davidlmobley]

Thanks, everyone, for the valuable feedback! I'm updating the to-do list accordingly.

@jchodera - I know you're a big fan of the eLife template; do you have thoughts on the suggestion to go to two columns (eliminating the gutter) after p1?

[davidlmobley]

This was closed by the updates to the templates which were merged ( #23 ).