0

I am writing a piece of technical text that can be read on its own (as a complete document) or as a section of a longer document. My concern is how to write an introduction without explicitly mention the words "document" and "section".

This piece of text discusses the design of a functionality of a software product. I want to be able to hand this text on its own and also put together all the functionalities of the product in a bigger document that makes sense.

In the introduction (or the lead paragraph), I am tempted to write sentences like:

  • "This section/document discusses..."
  • "this functionality is out of the scope of this section/document"

I am looking for a word (a generic term) that replaces "section" and "document" and works well in both cases.

The best option I found so far is "here":

  • "Here we discuss..."
  • "this functionality won't be discussed here"

Is "here" a good word for a technical document? if it is, how can I avoid the use of "we" and make it more impersonal?

Improve this question
2
  • 1
    Rather than saying that something is out of scope here, it would be better to refer to the place (volume/section/chapter) where it is discussed.
    – KillingTime
    Commented Dec 5, 2019 at 9:17
  • 1
    It’s best not to be too clever with things like this. Links and references to other documents usually don’t stand the test of time. Start your document with a brief statement of its scope and purpose. You can say something like “Our purpose here is to provide a concise introduction to X. There are other documents that provide more detailed information.” Your writing will most likely be revised, compiled and linked by others in the future, maybe even your future self. Don’t tie your hands needlessly.
    – user205876
    Commented Dec 5, 2019 at 16:49

1 Answer 1

Reset to default
2

“Here we discuss” is fine. If you make it impersonal/ passive, it will be “What is discussed here...” The second sentence, at the same time, is impersonal. As you say, it could be, “Here, we won’t discuss the functionality.” Make sure that you do not violate instructions of the publisher, if it is a journal kind of manuscript.

Improve this answer

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .