Reviewer 2 comment 1

[agitter]

My main concern (+ comments and questions below) is that the article is a bit technical and as such, addresses a technical audience. Since the paper has been submitted as a Software paper, maybe it's fine but it would be nice if non-technical people would also be able to read the paper (to realize open-source collaborative frameworks exists).

[slochower]

I don't have any good ideas for this. Perhaps we could add a figure showing how easy it is to make a PR, even through GitHub's web interface, to make changes to a manuscript. (1. Click Fork, 2. Edit some file in the web interface, 3. New pull request)? But showing screenshots of GitHub's web interface seems kind of clunky to me.

[agitter]

I don't good ideas here either. The reviewer may be picking up on some of the technical jargon-heavy paragraphs. We could do something like keep the main text about what Manubot can do and use Boxes or other asides to describe how Manubot does that from a technical standpoint. Part of the issue may be that the "Results" and "Methods" are integrated in each section.

[slochower]

Does anyone else have good ideas for reducing the jargon? I'm not sure any of the recent PRs have addressed the overall technicality. I can foresee a few ways forward:

1. Do nothing (which seems like it might be fine based on the reviewers' comments),
2. Go through the paper, identify technical phrases, and try to find alternates,
3. Add some less-technical stuff in introduction and conclusion, or
4. Try to separate the technical things from the nontechnical things (e.g., have a section that focuses on Manubot from a user's perspective and a separate section on development),

...or other stuff. What do other people think?

[agitter]

1 and 4 seem like the best options to me. We want this manuscript to serve as a reference for Manubot, so in previous discussions we were inclined to leave some of the technical discussion in. We could try to fine synonyms or add context for the most technical parts, but some of this is inherently heavy on jargon.

My vision for 4 is that we would need a separate "Methods" section that contains the technical aspects and a "Results" section that presents the user perspective. Do we want to undertake such a major rewrite? Would it be redundant if written that way?

[dhimmel]

I support 1 and when possible 3.

Having some takeaway from the manuscript for non-technical readers is a goal we should keep in mind. However, given the time it would take to majorly restructure or rewrite the manuscript, I think this should remain a guiding principal when making changes, but not something we specifically revise the manuscript for.

[agitter]

We can all look for places to provide context for technical terms where it is missing.

@dhimmel should one of us add an additional paragraph to the end of the introduction providing some key takeaways and Manubot features? The current intro spends more time on deep review than Manubot.

[dhimmel]

should one of us add an additional paragraph to the end of the introduction providing some key takeaways and Manubot features?

After #186, I can reassess this.

[agitter]

@dhimmel I can probably add this later today if you don't get to it. I'm imagining a short 3-4 sentence paragraph overviewing the big pictures idea of what Manubot is all about and its major benefits.

[dhimmel]

Okay I will not be able to do until tomorrow earliest. So feel free to take the lead if you have the time

[agitter]

I had time today. See my first attempt in #194.