This is an article that the community as a whole should be reading. TlL:DR version:
Abstract, jargon articles get cited less.
I would extend this to include documentation and online answers to coding questions.
1 Like
May be interesting. But clicking on the link with the desire to read the paper, I can now think of yet another - equally important - quality of articles, namely, accessibility. Not necessarily completely for free (I do agree that good work needs to be paid for in one way or another), but no, I am not gonna pay ÂŁ29.00 to read this paper.
15 Likes
Sorry, lets try this link
2 Likes
Oh wow, writing your paper in a readable manner makes it more citable??? What a surprise!!! 
Not necessarily completely for free (I do agree that good work needs to be paid for in one way or another)
To be honest, I think it should be completely for free and for everyone. The public already paid for this work via taxes (authors in interview are from university of arizona), so it should be able to read it on demand. The entire publishing system of science needs a revamp, but that’s another discussion…
9 Likes
I understand. And, in fact, I agree with the general idea. I only included that statement as a general reminder that there is no free lunch. Somebody always pays for it. In one way or another.
In this case, true, it is the tax payers who pay for a significant part of the cost of conducting the (academic) scientific research and bringing the results to the readers. But whether the whole cost, I am not sure, and frankly, I am not equipped to pursue a general discussion on this topic further. Here I only wanted to be slightly biting against the paper teaching us how to reach a wider audience while asking a reader to pay the nonnegligible fee of GBP 29, I found it funny, I confess 
1 Like
I’ve sent this to one of my coauthors whom is a lawyer by training.
Everything he writes, I have to rewrite because even I cannot understand it.
He took it as a funny joke though…
6 Likes
To obfuscate through meditative linguistic correlates is a dispassionate methodology of the egalitaristic hegemony to further the elitist propaganda.
4 Likes
https://documentation.divio.com/ is relevant and has been discussed at great length on this forum: Search results for 'divio' - JuliaLang.
One important point from previous discussions is that one-size-fits-all documentation is near impossible. In many circumstances, jargon is both unnecessary and confusing. However, there are many other circumstances (e.g. some reference documentation) where using shorthand is important because nobody wants to wade through a block of definitions they already know when searching for a specific piece of functionality. This is not limited to CS: I think most of us who work in other domains can think of examples there too.
Personally, I lean on this being a failure of powerful enough tooling. Question answerers generally calibrate their responses based on personal knowledge and the perceived understanding of the asker. The problem with this is that most platforms leave the answer as a dumb blob of text. If, say, we had better support for detecting and auto-linking to unfamiliar terms/jargon, then rich answers would be far easier to create. In the absence of such features, it becomes more of an economic problem. e.g. it takes me around 10x as much time to explain gradient descent and how a basic multi-layer dense neural net works (including finding good linked resources for further reading) than it does to point someone at the Flux tutorials and hope those do the trick.
1 Like
Ehh this article is a bit too abstract for me, so I’m not sure there’s much to implement from it. Don’t know if I’ll come back to it.
1 Like
Can we just appreciate the delicious irony that a post rallying the community to use better titles has “A useful article” as title?
12 Likes