1

I have some questions about the use of articles in the documentation of the Laravel framework.

The chunk method breaks the collection into multiple, smaller collections of a given size

Why is used the definite article before 'collection'? Is it considered as the specific collection that the method should be applied to? Ok. Then why is used the indefinite article in other similar descriptions like this:

The collapse method collapses a collection of arrays into a single, flat collection

More examples:

The firstWhere method returns the first element in the collection with the given key / value pair

Here it is used the definite article before 'given key / value pair'. But in the sentence below:

The where method filters the collection by a given key / value pair

The indefinite one. Why?

The last question is from the description of the definite article:

We use the definite article in front of a noun when we believe the listener/reader knows exactly what we are referring to

Why is used the definite article before 'listener/reade'? Do we suppose that the listener and reader are the hypothetical particular persons who are talking about something?

I'm confused. The search doesn't help. Explain to me pls

  • 2
    I think they are interchangeable in those contexts. – Colin Fine Jul 22 at 15:08
  • 1
    I think that the "Why?" here is answered by saying that this documentation was probably not written by a careful, professional technical writer, so the person (or people) who wrote this was not really trying to keep a consistent style of usage. – Canadian Yankee Jul 22 at 16:47
0

The following answer assumes some fluency in computer programming languages

In regards to the documentation referenced, I believe I was able to catch some of the intention. The intention is subtle and relates very specifically to software.

I should also note that the author made some assumptions about the reader that they shouldn't have.

When it comes to object oriented software, or software that defines classes with fields and methods, it is important to differentiate how methods are referenced.

Lets say I have a class Car with a method accelerate:

Car car = new Car();
car.accelerate();

When describing accelerate, technical documentation may refer to any instance of the class Car with "The method accelerate makes the car move" which can be interpreted as:

The method accelerate when called any instance of Car makes that instance move

By using "the" the author is assuming the reader understands this

Now lets say that Car has another method flash that only works when the instance of Car has high-beams.

When describing flash, technical documentation may refer to a specific instance of the class Car with "The method flash makes a car flash its high-beams" which can be interpreted as:

The method flash, when called on a specific instance of Car that has high-beams, makes that instance flash it's high-beams

| improve this answer | |
  • That is, in the first case with accelerate we don't know exactly what an instance we are talking about (any instance or that instance which the method is called on). Therefore we use the with car. In the second case with flash we know what the instance we mean and we can use a with car. But in the second case we can also use the. Right? – Roman Never Jul 23 at 7:31
  • I think you are right, and it is just a matter of style. IMHO, I would not use the documentation you shared to learn technical writing. If anyone finds a good example of technical writing, please edit the answer with a reference! I think it would be helpful – iraleigh Jul 24 at 4:02

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.