search

sunpy / sunpy-1.0-paper

The SunPy 1.0 Paper Repo
12 stars 21 forks source link

Jargon + small-scale copyediting issues #63

Closed mbobra closed 5 years ago

mbobra commented 5 years ago

I have one large-scale issue, and that is: How much technical jargon are we willing to allow into the paper? Do we want to allow the terms factory, subclass, class, method, base class, API, Pandas dataframe, subpackage? Do we want function names in the text?

There is a big difference in how each author approached these questions. For example, the Fido section (Section 7), does not use any of the words listed above. Instead, it is written in plain and conversational English. I personally prefer this style of writing, but I leave it to the team to decide.

There is also a big difference in the amount of detail associated with any given section. For example, some sections describe the underlying structure for a given object and how to convert it into different data types (e.g. an AstroPy Table, NumPy array, or Pandas dataframe). Others do not go into this level of detail. I personally prefer to refer the reader to the docs for data type conversions, but I leave it to the team to decide.

Here are a few small-scale issues:

nabobalis commented 5 years ago

My thoughts:

How much technical jargon are we willing to allow into the paper? Do we want to allow the terms factory, subclass, class, method, base class, API, Pandas dataframe, subpackage? Do we want function names in the text?

I think we should avoid any unless it serves a purpose in the context it is used in. Function names could be useful if we showcase an example like the diff_rot figure.

I personally prefer this style of writing, but I leave it to the team to decide.

I agree with you.

I personally prefer to refer the reader to the docs for data type conversions, but I leave it to the team to decide.

I agree with you. We should avoid replicating parts of our docs (or maybe including information that belong in the docs but are missing) in the paper.

  • open-source or open source,

open source

  • GSOC or GSoC, and

GSoC

  • Numpy, NumPy, or numpy for the actual library -- I suppose it should be numpy if we are going with sunpy.

Numpy, it seems that on their own website (https://www.numpy.org/) they use NumPy when referring to the package.

  • Maybe we can aggregate all the SunPy affiliations (e.g. Sunpy Deputy Lead Developer, SunPy Board Member) at the beginning of the affiliations list.

Yeah, that makes sense to me.

  • Some affiliations are repeated (due to minor differences in spelling and punctuations), e.g. 25 and 26. Maybe we can provide authors with an affiliation template.

We might have to tidy that up at the end when we have all the authors.

  • Do we want all the instruments in the TimeSeries and Map subsections written as a bulleted list or in a comma-separated paragraph?

I am worried a bulleted list might just be too long, so I would go comma-separated paragraph

ehsteve commented 5 years ago

How about we put the instruments supported into a table?

nabobalis commented 5 years ago

Seems overkill? But I can do so.

mbobra commented 5 years ago

How about we put the instruments supported into a table?

I think this is a super good idea. And we can have two columns indicating which are supported by TimesSeries and which are supported by Map.

nabobalis commented 5 years ago

Ok, give me a bit to do that!

mbobra commented 5 years ago

@ehsteve and I had a conversation earlier this afternoon about editing some of the jargon out of the paper in favor of more conversational English. We will also do some copyediting while we're at it.

I will PR Sections 0, 1, 2, 3, 4, and 5. I will add information about the release schedule (in the recently-approved SEP-0009) into Section 4 of the text.

@ehsteve will PR Sections 6, 7, 8, 9, 10, 11, 12 and 13.

ehsteve commented 5 years ago

Looks like most/all of the issues here have been addressed so I'm closing this issue.