I mostly agree, but I think in some cases, this advice oversimplifies. In particular, I think if one thing really just is another thing, it may be appropriate to emphasize that.
In source code and in our wiki, I have written “The Foo product just is a deployment of our monolith that doesn’t serve normal traffic, only…”
In that sentence, “just” adds emphasis, and could be omitted, but I think the sentence is better with that emphasis.
P.S. There’s probably a syntactic/semantic distinction you could draw between the different uses of “just”, but I don’t feel up to trying to draw it.
P.S. There’s probably a syntactic/semantic distinction you could draw between the different uses of “just”, but I don’t feel up to trying to draw it.
At a quick glance, I think there’s a relatively clear distinction between just meaning simply or only and just meaning exactly or precisely. (There are also other meanings altogether. E.g., He just made it. where just means barely.) That said, I can imagine cases where it’s hard to decide exactly which use an author intends.
On a charitable take, the author means for us to (just?) remove the uses that mean simply or only and not others. If I’m reading your example correctly, I think you are using just in the sense of exactly. You’re safe. :)
There is also a nuance where “just” means “this and no more” e.g. in the Django docs:
These profile models are not special in any way - they are just Django models that happen to have a one-to-one link with a user model.
In other words, there is nothing extra going on here. Or, you might have docs that say:
To enable this feature add just the following items to your config…
Meaning, “add the following and do not be tempted to do anything extra”.
This can sometimes contrast with:
To enable this feature just add the following items to your config…
Which implies “this isn’t going to be much work, it’s simple”. A native English speaker would understand the difference instinctively, although it’s a very small word order change.
“Just” basically means “literally only”, so it’s useful in the context of well-defined jargon and precise speaking, but is generally bad when you’re trying to convey a concept in few words, because the latter requires simplification and using “just” contradicts that.
In Zen and the Art of Motorcycle Maintenance, page 232, Pirsig described “just” as “a purely pejorative term, whose logical contribution to the sentence [is] nil,” when trying to analyze its usage and meaning. The history of “just” goes back to Latin, and its various meanings are concerned with justice and belief. In general, when somebody says “just”, they are saying “I believe that…”
In your example, I would interpret you to say something like “To this technical writer’s belief, the Foo product is a special deployment of our monolith which serves … instead of normal traffic.” And then, as Pirsig notes, the first clause is non-logical and only annotates the sentence as having some distinct epistemological foundation (based on the writer’s belief rather than e.g. evidence or cultural understanding); it can be dropped.
Personally, I try to avoid “just”. It has the nature of Iago to it, along with other words like “daresay”; it’s not just a weasel word, but a potent distorter of reality.
Personally, I try to avoid “just”. It has the nature of Iago to it, along with other words like “daresay”; it’s not just a weasel word, but a potent distorter of reality.
I’m not sure if you meant this to be a joke, but notice that in the second part of your sentence you’ve used just in a meaning that is distinct from the “I believe that…” meaning that you claim is dominant. In your sentence, just means only as it often does.
More importantly, I think that Pirsig, you, and teh_codez oversimplify. Words can mean lots of distinct things, and I think we do a disservice to writers and readers if we insist on trying to reduce complex words to (just—i.e. only?) one base meaning.
In this case I actually don’t think they mean distinct things at all. It’s more of a continuum. But, zooming out, focusing on the word “just”, or even a specific sense of the word “just”, is missing the point—belittling someone’s struggle is done using words, but it is not itself words. Blaming certain words for making the reader feel bad is like blaming certain chemical elements for making people get viruses.
In this case I actually don’t think they mean distinct things at all. It’s more of a continuum.
I’m not sure what you mean by this case, but (to be very blunt) the adverb just means several distinct things. I’m not sure why several people in this thread want to insist that they know better than dictionaries what just means. It’s an odd hill to die on.
It was a joke, yes. Remember that “but” means the same thing as “and”, logically; the logical content is the same as if I were to phrase everything with the subjunctive mood.
English is not a good language and we should not suffer its historical warts.
I love that my mind jumped to Rails wayyy before I got to the example.
Now that I think about it, this article gets at why I don’t get along with most web frameworks: they’re all built in such a way that they end up being thin conceptual layers over the web themselves, necessitating flipping back and forth between the docs because they tend to be not so high-level that you don’t have to think about the web and yet not so low level that you can only think about the web. So I end up having to hold in my head status codes, JSON encoders, alongside partials and template rendering junk.
Really good article. This is something I’m going to keep my eye on in the future while writing docs.
The title seems draw an extra conclusion that I don’t feel the article is necessarily making, however.
Reading that makes me immediately think of the Laravel documentation that is full os those, and I (very) midly annoying. I took me some time to figure out why I like Symfony documentation better.
I use a vim plugin (not my creation) to highlight words like, “easily”, or “simply” for exactly the reasons stated in the article.
When people say, “just” or “simply” theres usually a hidden prefix clause of, “(assuming you’ve already loaded the exact same context as the author)…”
[Comment removed by author]
I mostly agree, but I think in some cases, this advice oversimplifies. In particular, I think if one thing really just is another thing, it may be appropriate to emphasize that.
In source code and in our wiki, I have written “The Foo product just is a deployment of our monolith that doesn’t serve normal traffic, only…”
In that sentence, “just” adds emphasis, and could be omitted, but I think the sentence is better with that emphasis.
P.S. There’s probably a syntactic/semantic distinction you could draw between the different uses of “just”, but I don’t feel up to trying to draw it.
At a quick glance, I think there’s a relatively clear distinction between just meaning simply or only and just meaning exactly or precisely. (There are also other meanings altogether. E.g., He just made it. where just means barely.) That said, I can imagine cases where it’s hard to decide exactly which use an author intends.
On a charitable take, the author means for us to (just?) remove the uses that mean simply or only and not others. If I’m reading your example correctly, I think you are using just in the sense of exactly. You’re safe. :)
There is also a nuance where “just” means “this and no more” e.g. in the Django docs:
In other words, there is nothing extra going on here. Or, you might have docs that say:
Meaning, “add the following and do not be tempted to do anything extra”.
This can sometimes contrast with:
Which implies “this isn’t going to be much work, it’s simple”. A native English speaker would understand the difference instinctively, although it’s a very small word order change.
“Just” basically means “literally only”, so it’s useful in the context of well-defined jargon and precise speaking, but is generally bad when you’re trying to convey a concept in few words, because the latter requires simplification and using “just” contradicts that.
In Zen and the Art of Motorcycle Maintenance, page 232, Pirsig described “just” as “a purely pejorative term, whose logical contribution to the sentence [is] nil,” when trying to analyze its usage and meaning. The history of “just” goes back to Latin, and its various meanings are concerned with justice and belief. In general, when somebody says “just”, they are saying “I believe that…”
In your example, I would interpret you to say something like “To this technical writer’s belief, the Foo product is a special deployment of our monolith which serves … instead of normal traffic.” And then, as Pirsig notes, the first clause is non-logical and only annotates the sentence as having some distinct epistemological foundation (based on the writer’s belief rather than e.g. evidence or cultural understanding); it can be dropped.
Personally, I try to avoid “just”. It has the nature of Iago to it, along with other words like “daresay”; it’s not just a weasel word, but a potent distorter of reality.
I’m not sure if you meant this to be a joke, but notice that in the second part of your sentence you’ve used just in a meaning that is distinct from the “I believe that…” meaning that you claim is dominant. In your sentence, just means only as it often does.
More importantly, I think that Pirsig, you, and teh_codez oversimplify. Words can mean lots of distinct things, and I think we do a disservice to writers and readers if we insist on trying to reduce complex words to (just—i.e. only?) one base meaning.
In this case I actually don’t think they mean distinct things at all. It’s more of a continuum. But, zooming out, focusing on the word “just”, or even a specific sense of the word “just”, is missing the point—belittling someone’s struggle is done using words, but it is not itself words. Blaming certain words for making the reader feel bad is like blaming certain chemical elements for making people get viruses.
I’m not sure what you mean by this case, but (to be very blunt) the adverb just means several distinct things. I’m not sure why several people in this thread want to insist that they know better than dictionaries what just means. It’s an odd hill to die on.
I believe your ire may be misdirected. I apologise if I gave you the impression I was one of these people. Have a nice day.
It was a joke, yes. Remember that “but” means the same thing as “and”, logically; the logical content is the same as if I were to phrase everything with the subjunctive mood.
English is not a good language and we should not suffer its historical warts.
It’s possible for something to be simple, and for you to be unaware of how it works. Good documentation bridges the gap.
Don’t mistake ignorance for complexity.
The article is about how to write better documentation, not that things with documentation aren’t “simple”
I love that my mind jumped to Rails wayyy before I got to the example.
Now that I think about it, this article gets at why I don’t get along with most web frameworks: they’re all built in such a way that they end up being thin conceptual layers over the web themselves, necessitating flipping back and forth between the docs because they tend to be not so high-level that you don’t have to think about the web and yet not so low level that you can only think about the web. So I end up having to hold in my head status codes, JSON encoders, alongside partials and template rendering junk.
Really good article. This is something I’m going to keep my eye on in the future while writing docs. The title seems draw an extra conclusion that I don’t feel the article is necessarily making, however.
Reading that makes me immediately think of the Laravel documentation that is full os those, and I (very) midly annoying. I took me some time to figure out why I like Symfony documentation better.
While sometimes it can’t be so simple that you need to have docs, it’s worthwhile striving for it to be
That’s not what the article is about though
Alternatively
What does this contribute?