Documentation review c13c1b4

[TheChymera]

This is all based on c13c1b4.

General Remarks

(Stuff that recurs often, so I'm not going to spell out every instance)

• Please try to use a more formal tone. I know there's no reason for docs not to be hip and casual, but if the docs are to double as the academic summary, they should not include words like “nice”, and they should wherever possible avoid addressing the reader in the 2nd person. Also, try to minimize the instances in which you refer to us (the authors) as we; this is generally only appropriate in the discussion (“we believe...”), or when specifically reporting what we have done (“we performed...”, “we designed ...”). Cases of what the user may want to do should be addressed as “one” or “the user”.

Specific Issues

• https://github.com/IBT-FMI/NeuroGentooProject/blob/c13c1b496190f6790d0bd8c5209c5aca5fd1da5a/doc/Paper.tex#L72

  • "some sort of statistics" is not a particularly scientific expression, try something else, perhaps include 1-2 examples in parantheses
  • we are not doing neurology (which is a branch of classical medicine), try “biomedical imaging”.

• https://github.com/IBT-FMI/NeuroGentooProject/blob/c13c1b496190f6790d0bd8c5209c5aca5fd1da5a/doc/Paper.tex#L73

  • The reference seems to point to nowhere on the compiled document you sent. You should show a dependency graph here (e.g. the one from your presentation).

• https://github.com/IBT-FMI/NeuroGentooProject/blob/c13c1b496190f6790d0bd8c5209c5aca5fd1da5a/doc/Paper.tex#L77

  • Please be more explicit/formal with computing terms, “tarball” is jargon or slang even. Why not “tar archive” or “tar-format archive” if you want to be religious about the terminology. Then again, I think “binary archive” would be best, since .zip is also used.

• https://github.com/IBT-FMI/NeuroGentooProject/blob/c13c1b496190f6790d0bd8c5209c5aca5fd1da5a/doc/Paper.tex#L83

  • You should add at least one more point here: Ebuilds allow better integration for live and pre-release software, they also bring usage and development closer together by directly linking the user to upstream. Given the ebuild doesn't contain too many patches, bugs can reasonable be reported directly to upstream rather than going through the distribution bugzilla first.

... total fail, I seem to be unable to browse the rest of the sources (.md) by-line. @Doeme can you help me out? If not I can comment on the rest via a PR...

[Doeme]

God damned github doing markdown rendering without providing an opt-out

[Doeme]

I've uploaded them again as text-files, you can view those line-by-line

[TheChymera]

It's ok, I'll comment via a PR. I'll be making suggestions directly by changing your text, and broader comments about any one line or section will be on a separate line (after said line or section) prefixed with “!!!”.

[Doeme]

Why dont you just do it e.g. here: https://github.com/IBT-FMI/NeuroGentooProject/blob/master/doc/BLAS_Lapack.txt

Pull-requests are silly if everything is on master anyways

[TheChymera]

too late now, I moved straight to reviewing and din't check back.

I'd say you can get going with this while I work on the rest.

PRs aren't all bad, they do allow me to just go line by line in vim and correct easy msitakes in place rather than having to write statements about them.

[Doeme]

Works for me