aboutsummaryrefslogtreecommitdiff
path: root/paper.tex
AgeCommit message (Collapse)AuthorLines
2020-04-23Minor edits on Boud's great correctionsMohammad Akhlaghi-13/+12
Reading over Boud's edits, I noticed a few other parts that I could summarize more and corrected one or two other parts to fit the original purpose of the sentence better.
2020-04-23ConclusionBoud Roukema-9/+9
Reduction by about 5 words. Although it's true that the low-level tools - make, bash, gcc - are still being actively developed, only expert users will tend to notice the differences, and in this context, it's probably more useful to point out that these are actively *maintained*. (Comment: I felt that the first sentence in the Conclusion is missing one of the obvious criteria for handling big data - citizen control so that big data could hopefully become less Orwellian than it is right now, with GAFAM having the main big data databases that are used by AI researchers and will tend to affect people's lives more than traditional "scientific" databases. But there's no point adding this here, since the criteria that tend to satisfy the scientific requirements ("principles") and citizens' rights tend to overlap to a fair degree...)
2020-04-23Discussion/caveats section.Boud Roukema-27/+27
Reduction of about 50 words. There were a couple of expressions that look a bit like some sort of software/research analysis jargon, such as `Research Objects`, `Software Heritage`, `Machine actionable`. Unless these are defined, capitalising them makes the reader assume that there is some well-known formal meaning and that s/he has to search for that him/herself. As lower case expressions, the reader can guess some reasonable meanings of these. The word "embargo" was introduced for proposal 2) to handle the third caveat.
2020-04-23Further edits to summarize the parts corrected by BoudMohammad Akhlaghi-43/+39
[Compared to first submission to DSJ last week with 11436 words in raw PDF, we have decreased the paper by ~1000 words to 10493 :-)] As with the previous commits, the moment Boud changed the structure of sentences, I was able to find the redundancies and remove them! This is a fascinating feature of collaboration I had never felt before: it is so hard to find redundancies in my own raw text, but even a minor correction by someone else suddeny breaks my mental memories/barrier on the sentence, allowing me to be more critical to it! Anyway, besides such corrections, I fixed a few other things: 1) In the DSJ's recently published papers, ther is no `~' between "Figure" and its number. 2) I noticed that in `tex/src/figure-src-inputconf.tex' I was actually using manually input strings for the filename, checksum and size! This was contrary to the whole philosophy of Maneage(!), I must have rushed and forgot! So LaTeX variables are now defined and used.
2020-04-234.6 Project analysis - publicationBoud Roukema-14/+12
About 20 words less. The ArXiv URL is added - this adds no extra length in words, and some readers will not be familiar with ArXiv (although the COVID-19 pandemic has attracted attention to BiorXiv).
2020-04-234.5 Project analysis - multi-userBoud Roukema-4/+4
Increase by 5 words. We don't need to give a big warning here, but "Permissions management" is meant to be a brief way of saying that whether or not different users can really read/write/execute in subdirectories will firstly depend on whether the user who cloned Maneage has handled these permissions correctly and whether s/he is able to allow others to edit in his/her subdirectories. Comment: Users would have to check who else is logged in at the time, who else is running jobs, and so on. On a supercomputer this might make sense, to avoid unnecessary recompiles. Anyway, this edit summary is not the place to discuss this...
2020-04-234.4 Project analysis - git branchesBoud Roukema-12/+12
Reduction by 15 words. "Branch" is fine as a verb, and "off" is fine as a preposition; there's no need for a second preposition. "We branched off the main forest path onto a smaller path".
2020-04-234.3.6 Project analysis - configure filesBoud Roukema-13/+14
Length reduction by about 15 words. A semantically significant change is from `leading to more robust scientific results` to `evolves in the case of exploratory research papers, and better self-consistency in hypothesis testing papers`. I said this in a previous commit, but it can't hurt repeating: In the covidian epoch (though not only), it is especially important to distinguish bayesian type exploratory research (typical in astronomy or searching for a good COVID-19 treatment or vaccine) from hypothesis testing (clinical testing in double-blind random access trials with clinical trials methods published on a public registry prior to the trials taking place). In the latter case, you want your results to be analysed consistently with the plan published before the trials even begin, and ideally you want them to be published (or at least posted on the trial registry website) even if your results are insignificant, to avoid a publication bias in favour of significant results. Test homeopathy against placebos in 1000 independent experiments, analyse them all the same way, and 2-3 experiments will be significant at the 3 sigma level...
2020-04-234.3.5 Project analysis - downloadsBoud Roukema-5/+4
Reduction by about 7 words. I added "internet security" as an extra reason for having all the downloads in a single file. Modularity and minimal complexity in themselves generally contribute to internet security, but in this case, it's obvious that having all the communication with the outside world managed through a single file makes internet security management much simpler. I replaced the "fake URL" by the real one, because at least in the present format, the URL fits in nicely. So both `paper.tex` and `tex/src/figure-src-inputconf.tex` are modified in this commit.
2020-04-234.3.4 Project analysis - the analysis itselfBoud Roukema-14/+14
Reduction by about 20 words - minor rewording.
2020-04-22Acknowledged the help of Idafen in ManeageMohammad Akhlaghi-0/+1
Idafen has helped in testing Maneage a lot during the last year and has provided very useful feedback and suggestions.
2020-04-22Applied futher comments by KonradMohammad Akhlaghi-7/+8
Regarding Docker Konrad pointed out that "Linux has an excellent track record for stability. It's more likely that the Docker itself becomes incompatible with older containers. Docker isn't developed for reproducibility after all". So I tried to modify that paragraph to include this important point too. In the process, I also shrank it a little more (without loosing anything substantial), so it doesn't add to the paper's length.
2020-04-22Minor edits to summarize section on project.tex and verify.texMohammad Akhlaghi-15/+13
After going through Boud's corrections, I thought it can be further summarized without loosing any major point.
2020-04-224.3.3 Project analysis - verificationBoud Roukema-6/+6
Reduction by 4 words. Minor rewording; removal of "Note that" and "simply" (the opposite of "complicatedly"). If a checksum is simple for a given user, then s/he already knows that; if s/he doesn't yet know what a checksum is, then stating that it's simple doesn't help very much. :)
2020-04-224.3.2 Project analysis - values within textBoud Roukema-11/+11
Reduction of about 15 words. The phrase "which does not need it" is removed. On its own, this is a claim, not an explanation. If the reader is wondering why `paper.tex` is not a produced file, then stating that the file is not needed will not help very much. Looking at the diagram will show that `paper.tex` is the overall article template; and the diagram strongly suggests that values from initialize.tex, ..., are passed into verify.tex, and from there into project.tex, which goes into paper.tex. The phrase "files, possibly in another subMakefile" should really be something like "files, possibly created by another subMakefile". But this would add more words, and given that the user has full control to modify and adapt the overall scheme (including making a mess of it), we can safely drop the info that the scheme can be made more complicated. :)
2020-04-224.3.1 Project analysis - paper.pdfBoud Roukema-2/+2
Only 3 words are reduced in this commit, but I think the improvements are worth it. "Note that" and "It is worth mentioning" are phrases still quite often used by academics (even in astronomy) that can be politely described as "pontification" or informally as "empty blabla"; these add no meaning except "I am teaching you something and I expect you to pay attention to what I am saying". :) There are also less polite descriptions.
2020-04-224.3 Project analysis introBoud Roukema-17/+17
Minor rewording of 4.3 Project analysis - introduction. Reduction of about 40 words. 4.2 `parallel` quote: s/http:/https:/
2020-04-22Implemented Konrad's suggestions, minor edits here and thereMohammad Akhlaghi-65/+64
Today Konrad made the following suggestions after reading through the paper (created from Commit 1ac5c12). Thanks a lot Konrad ;-). I tried to address them all in this commit. Afterwards, while looking over the corrected parts, some minor edits came up to me to remove redundant parts and add extra points where it helps. In particular to be able to print the International Phonetic Alphabet (IPA), I had to include the LaTeX `TIPA' package, but it was interesting to see that it was already available in the project as a dependency of another package we loaded.
2020-04-20Added link to citation from GNU Parallel, slightly summarized itMohammad Akhlaghi-1/+1
Boud previously pointed out that that he couldn't find a reference to the citation, so I added it as a link over "its FAQ" (since its described in its `doc/citation-notice-faq.txt' file). I also removed the first part of the quote which was not really necessary, the heart of the quote is the latter part that still remains.
2020-04-20Minor edits on Boud's corrections to mergeMohammad Akhlaghi-33/+31
I tried to make it slightly shorter, but I felt that it is important to keep the quote from GNU Parallel and in particular the financial aid it asks for. It will help readers feel the gravity of the sitution for this software author. The precise citation of the quote was given in the long version.
2020-04-20Minor copyedits - 4.2.2 software citationBoud Roukema-14/+12
This reduces the length by about 70 words. The biggest change is to remove what looks like a citation from `parallel'. I couldn't find the citation in GNU parallel 20161222-1 (Debian/stretch), nor with search engines. I don't think that the quote is really so useful (even assuming it's a valid quote from somewhere): citation practices are a mix between ethics, preparation to convince referees, citing those who are already cited frequently, and the practicality of searching for and verifying references against the information for which they are used. Showing that Maneage makes citation not only easy, but more or less automatic, bypasses some of the compromises between practicality and ethics.
2020-04-20Minor copyedits - 4.2.1 source verificationBoud Roukema-8/+8
Minor rewording; a reduction of about 12 words.
2020-04-20Minor copyedits - 4.2 intro configurationBoud Roukema-9/+9
Minor edits - reduces about 17 words.
2020-04-20Minor copyedits - 4.1 Maneage orchestrationBoud Roukema-13/+13
This commit reduces about 25 words from the 4.1 Maneage orchestration, aka `make`, section.
2020-04-20Minor edits to 4 Maneage introBoud Roukema-11/+11
This drops the word count in the introductory part of the Maneage section by about 15 words.
2020-04-20Clarfication on free software complementing reproducibilityMohammad Akhlaghi-1/+1
Thanks to Boud's corrections, I see that the sentence can be confusing and not convey the point I wanted to make properly, so I am clarifying it here. The main point is that this principle complements the definition of reproducibility, not the other principls.
2020-04-20minor language editsBoud Roukema-4/+4
These tiny language edits add 1 word in length.
2020-04-20Boud moved to third author, Lyon affiliation for Mohammad, minor editsMohammad Akhlaghi-16/+17
Boud has contributed a lot to Maneage over the last few years and with the last few commits he also contributed significantly to this paper, so I am moving him to third author. Thanks to Boud, I also remembered that even though I done the most important parts of Maneage in Lyon, I hadn't added it as an affiliation for myself, so I added it. Maneage became a separate project in Lyon. Finally, I tried to decrease the length of the acknowledgments by adding some abbreviations that were shared between various parts.
2020-04-20boud authorship/affil/acknowlBoud Roukema-3/+10
Unfortunately, adding in my name/affiliations/acknowledgments adds about 90 words to the text. We don't really know if these are counted by the editor in the 8000-word limit. I changed `funded' to `funded/supported'. I only get funding from one out of the three sources I acknowledge, but it's important to acknowledge all three.
2020-04-20Minor edits in the textMohammad Akhlaghi-4/+4
While looking over the PDF, a few small edits were made to be more clear.
2020-04-19Imported the recent parallel works on the principles sectionMohammad Akhlaghi-65/+64
The conflict was only on the list of existing tools and that was easily corrected.
2020-04-19Further summarized the principles sectionMohammad Akhlaghi-50/+49
Following Boud's great corrections, I was able to futher summarize this section, decreasing roughly 150 more words from this section.
2020-04-19List of existing tools made cleaner in LaTeX sourceMohammad Akhlaghi-1/+11
Until now the list of existing tools was written in one line which made it hard to read and follow, especially since we added links. It is now expanded into a one-line per item which makes to no difference in the final PDF.
2020-04-19Principles - P7 FOSSBoud Roukema-5/+5
Reduction by 15 words.
2020-04-19Principles - P6 ScalabilityBoud Roukema-2/+2
Reduction by 7 words. For a regular GNU/Linux of other unix-like system user, the bit about ISO C compilers even existing for Microsoft systems more or less says "despite there being no point ever trying to do science on a Microsoft system, you *could* hypothetically compile and run any ISO C program on it". Interesting, but not directly of interest to this user, who is unlikely to actually want to do it. A Microsoft user who thinks that s/he can do science on a Microsoft system will typically think "Microsoft is good, so of course I can run anything I want on it". So the message here could more likely be seen as provocative rather than useful, since this user is unaware of the fundamental problems of Microsoft as an authoritarian, manipulative, centralised organisation providing bad software. So either way, the parenthesis about Microsoft can be safely removed given the space constraints.
2020-04-19Principles - P5 History and temporal provenanceBoud Roukema-3/+3
Reduction by 5 words. The term "exploratory research" is intended in the specific sense listed at en.Wikipedia: https://en.wikipedia.org/wiki/Exploratory_research to distinguish it from hypothesis testing. The final phases of clinical (medical) research, for example, to test whether a candidate SARS-CoV-2 vaccine is (i) effective and (ii) safe in homo sapiens, cannot accept the exploratory methods that are acceptable in astronomy, or in other exploratory research (which is acceptable in the early stages of medical research). Clinical trial registration is aimed at *preventing* scientists from modifying their methods in a given project: https://en.wikipedia.org/wiki/Clinical_trial_registration
2020-04-19Principles - P4 verifiable inputs and outputsBoud Roukema-1/+1
One superfluous word was removed.
2020-04-19Principles - P3 minimal complexityBoud Roukema-5/+5
Minor wording changes - reduction by 10 words.
2020-04-19principles - P2 modularityBoud Roukema-6/+6
Minor wording improvements; reduction by 10 words.
2020-04-19principles: all nounsBoud Roukema-2/+2
For consistency, the principles should either all be nouns, or all be adjectives. Most are nouns, so this commit switches the adjectives to nouns.
2020-04-19Principles - P1 - CompleteBoud Roukema-19/+19
Compression by about 40 words. Updating python2 to python3 is often nothing more than modifying print statements, so removing this doesn't weaken the text by much. Re-creation helps avoid thinking of watching movies, going to the beach, reading a novel, when seeing the word "recreation": https://en.wiktionary.org/wiki/recreation#Usage_notes The matplotlib sentence was not so clear: now it's a bit shorter and hopefully clearer.
2020-04-19Principles introBoud Roukema-3/+3
Word-length reduction (8 words) of the first part of 3 Principles. Change in meaning: we can argue that *results* are not part of science, but science needs aims as well as methods; hypotheses are needed too, but these overlap between the aims and methods. So I put "primarily".
2020-04-19Clickable URLs for the 19 earlier reproducibility solutionsBoud Roukema-1/+1
In this commit, the URLs for the 19 "earlier solutions" at the beginning of "3 Principles" are recovered from tex/src/paper-long.tex and put behind the package names as clickable words. To reduce the chance that these are interpreted as references, "Project1 (yyy1), Project2 (yyy1)" is changed to "yyy1: Project1, Project2". We cannot add full references because of the 8000-word space constraint. With a minor word improvement, this commit overall reduces the word count very slightly, by 9, according to pdftotext paper.pdf |wc paper.txt before and after the commit.
2020-04-18Added arbitrarily complex to description of scalabilityMohammad Akhlaghi-1/+1
Scalability is not just on the size of the project, but also its complexity, so I added an `and/or complex' to the description of the scalability principle.
2020-04-18Added Scalability as a principle, minor edits/clippingsMohammad Akhlaghi-20/+38
Someone reading the principles section until now would think that IPOL is an almosts perfect solution, and for its usecase it certainly is. However, this is only because of the nature of its work: it only focuses on algorithms, not usage/analysis which cannot be done in raw ISO C. So with this commit, I added a new principle on Scalability and discussed this limitation of IPOL there. To avoid simply lengthening the text, to add this new principle, I had to remove/summarize some parts that seemed redundant. In the process, I also removed some of the existing tools (at the start of the principles section) that had several others in the same time frame, I have already mentioned (through the "and many more") that this list is not complete. Also, the list of people to thank in the acknowledgments is now put in a one-line per name to be more easily maintainable: Boud and Mohammad-reza were added, and given that I have sent the paper to several other people for feedback, I expect the list to get longer.
2020-04-18Minor language edits in paper.texBoud Roukema-7/+7
A few more minor language edits. For parseable vs parseable, see https://en.wiktionary.org/wiki/parsable which recommends `parsable` for formal usage.
2020-04-18Minor language edits in paper.texBoud Roukema-6/+6
These are mostly minor language edits. There is one significant fix: the word `typically' in `a non-free software project typically' cannot be distributed by the project. There is a whole range of licences between strictly free software definition, strictly OSI open-source definition, and fully closed source. For example, software with a no-commercial usage licence (similar to CC-BY-NC) can be publicly redistributed on any server, as long as there is no requirement of payment or no requirement of payment that is "commercial" (according to lawyers' interpretation of when a payment is commercial).
2020-04-18Two papers cited, for research software and data management plansMohammad Akhlaghi-39/+35
These are important aspects that are highly relevant to Maneage: its philosophy (the former) and usability (the latter). To add them, I tried to summarize some other parts of the paper.
2020-04-18Corrected several instances of n't to notRoberto Baena-Gallé-3/+3
Three such cases and they are fixed.
2020-04-18Edits in the text to make it shorter and fix a few mistakesMohammad Akhlaghi-20/+14
A few minor issues were found and fixed in the text. I also tried to shorten it a little further.