Paper outline (please add your opinion)

[asmeurer]

Based on a call with @scopatz and @moorepants, I have created a wiki page of the outline of the paper, with page counts for each section. This should hopefully allow us to resolve https://github.com/sympy/sympy-paper/issues/55.

Everyone: please go to https://github.com/sympy/sympy-paper/wiki/outline and add how many pages you think each section should be in the final paper (or add sections, if you think they are missing). The total page count should add up to no more than 18. This doesn't include any content from the supplement, which can be as long as we like.

I have the outline for the current paper as it stands at the bottom for reference (with assumption that the intro will be a page and the conclusion will be half a page).

Please do this by Monday, May 9. I am also creating some milestones in the issue tracker so that we are all on the same page with respect to deadlines.

[moorepants]

Thanks Aaron. I added my thoughts. I also broke "Uses of SymPy" into two sections, as I wasn't sure what you meant by that. Furthermore, I tried to write a brief statement that explains what would be in that section.

[moorepants]

We should send an email to the authors about this. Are you planning to do that, or would you like me to?

[asmeurer]

All major authors are collaborators on this repo so should have received a notification email already. If you feel that's not enough, feel free to send emails of your own.

[moorepants]

I filter all the github notifications myself and only look at them when I have time. With a Monday deadline, I think would be a courtesy to send out an email that might be noticed so we can get some contributions. I'll send an email.

[certik]

@asmeurer, @moorepants why don't you send an email into the sympy mailinglist.

[moorepants]

I didn't send it to the mailing list because we aren't trying to reach consensus from the 100s of people on the mailing list, we just wanted to have the current authors offer their thoughts on this so we can move forward. I can send it to the mailing list but I think we already have involved the people who care about the paper. And as it stands it seems only Aaron and I care about this Outline, as we're the only ones to edit it before the now closed due date.

[certik]

@moorepants well, I bet half the people didn't see this issue, especially those that are interested in contributing, but didn't get to it yet.

Many people care about the outline, including myself.

However, since everybody is busy, we simply have to set deadlines and do the work. And it might be, that some people are not able to contribute, even if they wanted, simply because they are too busy.

So I will assemble a list of people who have replied to me that they are interested in contributing, and email them myself.

[certik]

Also, we can then use this "mailinglist" to keep people updated on important deadlines.

[moorepants]

I sent a personal email to all of the authors about this issue on Friday. So there has been an email and the notifications of this issue.

[certik]

Yes, I got it. I will resend it to the people who are not yet authors.

[moorepants]

Before you send it we now need to make a new deadline.

One thing that @scopatz, @asmeurer and I discussed Friday was the deadlines. Aaron and Anthony have set deadlines for this and I asked them to make the schedule more clear to the rest of us. Aaron has set up the milestones to do this. They want to finish the paper and submit by May 26.

At some point we have to be firm about deadlines if we want to get it done by their desired due dates.

[certik]

I forwarded your email to 10 more people, who have expressed interest to me in the past. I don't think we have to set more deadlines. If they want to contribute, they have the chance now.

Note that if the paper doesn't feel right, once we have a draft, we might need to revisit the outline, that's just the nature of it. It's hard for me to judge by just number of pages.

[asmeurer]

From my point of view, the deadline is important, so just sending this to more people and postponing it isn't going to help that.

I would appreciate it most if you filled it out, @certik. You have been the most active person on the paper who hasn't filled it out yet. The next step is to take everyone's answer and decide what we will actually do by Wednesday.

[moorepants]

Note that if the paper doesn't feel right, once we have a draft, we might need to revisit the outline, that's just the nature of it. It's hard for me to judge by just number of pages.

I agree with this, but someone will have to draw a line somewhere about how it "feels" otherwise we will never finish. The outline's purpose is two fold:

1. Agree on the topics that the paper should cover.
2. Agree on how much paper space should be used for a given topic.

If we have that in place, then when people make edits and additions we can use this as a guide for the editorial decision making.

Now if the outline produces a bad paper, we will have to decide to make a new outline or just submit it as is.

From my point of view, the deadline is important, so just sending this to more people and postponing it isn't going to help that.

+1

[certik]

@asmeurer, @moorepants I did fill in the section about domain specific. I honestly do not have an opinion on the rest, because I need to see the content. As an example, 4 pages of crap about education would be terrible, but 4 very very good pages with lots of good content about education could make a lot of sense. I feel exactly the same about all the other sections.

For this reason, I prefer the iterative approach of seeing some kind of content first, and then see which sections to expand or shrink. @asmeurer said that's not the way he wants to do it --- and that's fine with me, he is the main person behind this, I respect the way he wants to do it.

So as the wiki currently stands, I am broadly ok with it and it looks like we have consensus. The disagreement seems to be in moving some sections to the intro. Either is fine with me. I want to see the draft, read it, and then I will have a lot more opinions.

[asmeurer]

@certik most of the content is written. For instance, the architecture/numerics stuff is already written down, at least as a first draft. So if you like what's there, you can put 7 (the current page count). If you think there should be more, or less, you can put a bigger, or smaller number. The page counts for the current paper are at the bottom of the page.

The ultimate question here is, does any of the stuff that is already written need to be cut down (moved to the supplement), and is there anything that isn't there that needs to be written. Jason, Anthony, and I agreed on our call on Friday that this was the most effective way to decide this, since it makes it very clear to everyone what everyone thinks should be in the paper.

Your input here would be helpful, since we will be deciding on what we will actually do between now and Wednesday (according to the schedule that I have set up in the milestones).

[asmeurer]

And I want to add that doing things iteratively is what we have been doing thus far. But we've reached a point where we should be finished with all major content, but there have been disagreements over what should be in the paper (see the discussion at https://github.com/sympy/sympy-paper/pull/84). Hence, we're doing this to make sure that everyone is on the same page with that.

[certik]

Thanks @asmeurer for the clarification. I am working on the paper now, will post my feedback soon.

[moorepants]

I honestly do not have an opinion on the rest, because I need to see the content. As an example, 4 pages of crap about education would be terrible, but 4 very very good pages with lots of good content about education could make a lot of sense. I feel exactly the same about all the other sections.

For this reason, I prefer the iterative approach of seeing some kind of content first, and then see which sections to expand or shrink.

The problem with this is that if I were to spend 15-20 hrs writing a nice section on the impact in education, research, and industry and you all scrap it instead of improving it, I would be out that amount of time.

The other way to do it is that the authors agree on what should be in the paper and then they all work to create the best content possible for the agreed upon sections. I don't have time to spend tons of hours on something to have it removed from the paper.

I personally want to see some different content in the paper and have it tell a slightly different story than what is there (as reflected in my outline votes and comments). I am willing to put in the time to create it, if I know it will actually stay in the paper (i.e. my draft improved upon by the other authors).

But if people don't think any new content is needed, then that's fine we can leave the paper as is.

From the iterative method, people could start writing and we end up with 18 pages of stuff about the architecture and features (which sorta happened). This could be beautiful and perfectly written, but then that leaves no room for sections that other authors may think should be in the paper. So how is that resolved? Do we choose the 18 pages of arch/features because it is great work or do we reduce it to make room for other things?

I think we should assume that we can produce quality material for any section we agree should be in the paper and then work together to create that.

[certik]

@moorepants ok, let's do it your way. I will have the section numbers later today.

[asmeurer]

So now that we've got this worked out, let me try to summarize:

• I think we all agree that we should spend a little bit (no more than a page each at most) discussing the community and scipy ecosystem. We don't agree if it should go in the intro or not (I personally don't really care. I think the actual section organization of the paper will need to change anyway).

• There's disagreement on the architecture. Anthony and I think it should be more. Jason thinks it should be less. Anthony, what would you add that isn't there? Jason, what would you remove that is there?

  I also want to point out here that the numerics section could be helpful for getting the paper accepted by SISC (our current target), which, as Andy pointed out, primarily features numerical articles.

• Features: Anthony, and Jason based on his comment, think there should be less or none of this. I think it should be there (although less than what's currently there).
• Domain specific stuff: The thing the most people seem to care about. Jason doesn't like it. I'm ambivalent, leaning toward moving it to the supplement. Brian, Anthony, and Ondrej want to keep it (and potentially expand it).
• Uses of SymPy: Jason split this up (his split seems fine to me). I think it's worth having a couple pages. Jason wants to see more for "impact" uses, but less for "software dependency" uses. Anthony wants to see less of this (basically, just mentions in the intro/conclusion).
• Comparison to other CASs: Jason wants to see more of this. Anthony and I want to see less.
• Conclusions and future work: Jason and I think it should be shorter. Anthony thinks it should be longer. I'm actually fine with a longer section here if we have the space, if someone writes it (I personally really suck at writing conclusions for anything).

@moorepants @scopatz @certik @ellisonbg does that sound like an accurate summary to you?

Based on that, I think the things we need to decide on are:

1. What should be added/removed (based on your opinion) from the architecture?
2. What should the "features" section look like?
3. Should we have a "domain specific" section?
4. Should we list out software that uses SymPy, or just mention the big ones in the intro?
5. Should we have a section dedicated to "Research, Education, and Industry" uses of SymPy?
6. Should we have a "Comparison to other CASs" section?

And keep in mind that if your opinion for any of those items is that we should add stuff that isn't written already, that someone will need to actually write it ;)

[asmeurer]

@moorepants you added the section descriptions. You wrote

SymPy's Role in the Scientific Python EcoSystem:

Explains how SymPy uses and is used by other software packages in the "SciPy Stack".

Jason: 1

and

Software projects that use SymPy:

Says that SymPy is used as a library and lists software projects that use SymPy in this fashion.

Jason: 0 This could be a one or two sentences, maybe mentioning a couple of main ones like Sage, in the main text and the extenisive list should be in the supplement.

These seem to be the same to me.

I think we have no disagreement here, just a different naming of section titles.

[asmeurer]

My opinions:

(1) What should be added/removed (based on your opinion) from the architecture?

Nothing. I think what's there is good (modulo edits, which will start later this week). I think we should keep the numerics section, for the reason I noted above (it will help us get into the journal). And I also think it's one of the better parts of the paper as it currently stands, which I realize is a weak argument since all parts of the paper will need to be improved before we submit anything.

(2) What should the "features" section look like?

I think we need to hit the big points. For me those are basic usage, simplification, simple calculus, a blurb on printing, something about solve, and something about matrices. I also like having the table with every feature listed.

With that being said, what is there for many of these things is still already too much, and I've been trying to cull things down and move stuff to the supplement from this section (e.g., I'm now thinking the "sets" section should go to the supplement as well).

(3) Should we have a "domain specific" section?

We can have this, but I don't think it should be very long. I don't think it's worth having a subsection for each little feature. For instance, units is a very small subsubpackage of SymPy, barely even used in other parts of SymPy. It doesn't deserve it's own paragraph.

Basically, there are a ton of features of SymPy, and most of them won't get any mention beyond the features table. So there needs to be a good reason to explore some feature in any kind of depth, like say, vectors, when other features, like geometry get no mention at all (and I don't want to single anybody's pet feature out here).

(4) Should we list out software that uses SymPy, or just mention the big ones in the intro?

I think Jason is right here. Let's move the current list to the supplement, and just mention the big ones. The only advantage of having the list in the paper is if we for some reason wanted to have citations for all of them in the paper (and even then, we could just write something like "SymPy is a dependency of many projects ").

(5) Should we have a section dedicated to "Research, Education, and Industry" uses of SymPy?

I think no.

(6) Should we have a "Comparison to other CASs" section?

No. This would be nice to have, but all we have is a comparison to Mathematica, which isn't very balanced. Having just this would also implicitly position SymPy as a "Mathematica alternative", which I don't think is how we want to sell SymPy (we should be selling it on its own merits).

[certik]

I essentially agree with @asmeurer.

• Yes, adding (and even then, we could just write something like "SymPy is a dependency of many projects <long list of citations here>"). and move the list to supplement seems like a good idea.
• The "domain specific" section is already 2 pages. I think we can shorten each section, remove units (I agree with Aaron). I would however expand the classical mechanics (that's a big deal, actively developed, e.g. see recent @isuruf's speed improvements using symengine there), and the quantum mechanics should be polished by @ellisonbg and perhaps @rpmuller.

[asmeurer]

OK, it sounds like a lot of people want the domain specific stuff, in particular classical mechanics and the quantum stuff. The deadline for new content is Monday, so if we can get content for the quantum stuff by then, then it's fine by me.

No one else seem to have any opinions on anything else (and today was the deadline to discuss this stuff), so I guess everyone's OK with my views above?

[certik]

I am fine with them. @scopatz, @moorepants ?

[moorepants]

Haven't had time to read and respond, very busy first few days of the work week.