Fixes in dev docs #3333

grobmeier · 2024-12-26T16:56:01Z

Improved writing (active/passive, typos, grammar) for several pages.
FInal checks for MS30: #1867

src/site/antora/modules/ROOT/pages/development.adoc

vy · 2024-12-28T18:38:35Z

src/site/antora/modules/ROOT/pages/faq.adoc

 Note the `2` in the file name!
 (See xref:manual/configuration.adoc[the Configuration page] for more details.)

 . Increase the logging verbosity of the internal xref:manual/status-logger.adoc[]: +
 `-Dlog4j2.statusLoggerLevel=TRACE`

 . Enable all internal debug logging: `-Dlog4j2.debug`.
-This disables level-based xref:manual/status-logger.adoc[] filtering and effectively allows all status logs.
+This turns-off level-based xref:manual/status-logger.adoc[] filtering and effectively allows all status logs.


We technically always use enable and disable to denote activation – I think we should stick to that.

Disabled people will thank us for not using this terminology. We can keep it, but I think it is a negative wording. Please confirm you want to do that.

Disabled people will thank us for not using this terminology.

You mean "people with disabilities" 😉? I don't think anybody thinks about physical disabilities, when reading a technical documentation, but if we are going to ban the disable verb, we should do it in the entire documentation.

Please confirm you want to do that.

@grobmeier, I confirm that I prefer replacing turns-off with disables. Though I leave it to your discretion.

How about "This allows for all kinds of status log messages to be written" or something like that.

Co-authored-by: Volkan Yazıcı <[email protected]>

ppkarwasz · 2024-12-29T11:37:32Z

src/site/antora/modules/ROOT/pages/development.adoc

 See {logging-services-url}/logging-parent/release-instructions-xml-schema.html[its release instructions for XML schemas].

 [WARNING]
 ====
 **Projects and XML schemas have different lifecycles!**
-A new release of a project does not necessarily mean a new release of its XML schemas.
-XML schemas might have been untouched, or they might contain minor changes while the project itself contains breaking changes, etc.
+A project's new release does not necessarily mean a new release of its XML schemas.


Suggested change

A project's new release does not necessarily mean a new release of its XML schemas.

A new project release does not necessarily mean a new release of its XML schemas.

ppkarwasz · 2024-12-29T11:38:25Z

src/site/antora/modules/ROOT/pages/faq.adoc

-                       https://logging.apache.org/xml/ns
-                       https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+ https://logging.apache.org/xml/ns
+ https://logging.apache.org/xml/ns/log4j-config-2.xsd">


I prefer the previous indentation.

ppkarwasz · 2024-12-29T11:39:48Z

src/site/antora/modules/ROOT/pages/faq.adoc

 This is not the case: applications coded to Log4j API always have the option to use any SLF4J-compliant logging implementation with the `log4j-to-slf4j` bridge.
 See xref:manual/installation.adoc[the Installation page] for details.

 There are several advantages to using Log4j API:

 * SLF4J forces your application to log ``String``s.
 Log4j API supports logging any `CharSequence` if you want to log text, but also supports logging any `Object` as is.
-It is the responsibility of the logging _implementation_ to handle this object, and we consider it a design mistake to limit applications to logging ``String``s.
+The logging _implementation_ is responsible for handling this object, and we consider it a design mistake to limit applications to logging ``Strings``.


Suggested change

The logging _implementation_ is responsible for handling this object, and we consider it a design mistake to limit applications to logging ``Strings``.

The logging _implementation_ is responsible for handling this object, and we consider it a design mistake to limit applications to logging ``String``s.

I prefer not to modify the name of classes.

ppkarwasz · 2024-12-29T11:40:53Z

src/site/antora/modules/ROOT/pages/faq.adoc

 The solution is to provide the correct FQCN.
-The easiest way to do this is to let Log4j generate the logger wrapper for you.
+The easiest way is to let Log4j generate the logger wrapper for you.
 Log4j comes with a Logger wrapper generator tool.
 This tool was originally meant to support custom log levels and was moved to the
 {logging-services-url}/log4j/transform/latest/index.html[Log4j Transform subproject].


The tool was removed from Log4j Transform too, should we remove this paragraph?

@ppkarwasz, good catch, yes, we should.

jvz · 2024-12-30T17:34:08Z

src/site/antora/modules/ROOT/pages/development.adoc

@@ -54,7 +54,7 @@ The following branching scheme is followed:
 `<sourceBranch>-site-<environment>`::
 `<sourceBranch>-site-<environment>-out`::
 Branches used to serve the staging and production websites.
-`out`-suffixed ones are automatically populated by CI, you are not supposed to touch them.
+CI automatically populates `out`-suffixed ones; you are not supposed to touch them.


Suggested change

CI automatically populates `out`-suffixed ones; you are not supposed to touch them.

CI automatically populates `out`-suffixed branch names; you are not supposed to touch them.

jvz · 2024-12-30T17:37:49Z

src/site/antora/modules/ROOT/pages/development.adoc

 +
 [TIP]
 ====
-You are strongly advised to spar with another maintainer first (see {logging-services-url}/support.html#discussions-maintainer[maintainer discussion channels]) before starting to code.
+We strongly advise you to spar with another maintainer first (see {logging-services-url}/support.html#discussions-maintainer[maintainer discussion channels]) before starting to code.


Is "spar" the right term here? I only know that in context of practice martial arts fights (and apparently it's some part of a ship). I might go with something like "discuss" here.

jvz · 2024-12-30T17:38:37Z

src/site/antora/modules/ROOT/pages/faq.adoc

@@ -18,7 +18,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
 = F.A.Q.

 This page compiles a list of frequently asked questions.
-If you don't find the answer to your question, please consult to link:{logging-services-url}/support.html[the support page].
+If you don't find the answer to your question, please consult the link:{logging-services-url}/support.html[the support page].


Suggested change

If you don't find the answer to your question, please consult the link:{logging-services-url}/support.html[the support page].

If you don't find the answer to your question, please consult link:{logging-services-url}/support.html[the support page].

"The" is repeated otherwise.

jvz · 2024-12-30T17:57:51Z

src/site/antora/modules/ROOT/pages/faq.adoc

 Note the `2` in the file name!
 (See xref:manual/configuration.adoc[the Configuration page] for more details.)

 . Increase the logging verbosity of the internal xref:manual/status-logger.adoc[]: +
 `-Dlog4j2.statusLoggerLevel=TRACE`

 . Enable all internal debug logging: `-Dlog4j2.debug`.
-This disables level-based xref:manual/status-logger.adoc[] filtering and effectively allows all status logs.
+This turns-off level-based xref:manual/status-logger.adoc[] filtering and effectively allows all status logs.


How about "This allows for all kinds of status log messages to be written" or something like that.

grobmeier added 3 commits December 26, 2024 17:42

fixed active/passive voice, minor grammar/spelling.

bc34613

active/passive, writing for clarity

c0a694f

active/passive

02fb184

grobmeier requested a review from ppkarwasz December 26, 2024 16:56

vy requested changes Dec 28, 2024

View reviewed changes

corrected capitalization

a8602bc

Co-authored-by: Volkan Yazıcı <[email protected]>

ppkarwasz approved these changes Dec 29, 2024

View reviewed changes

jvz reviewed Dec 30, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fixes in dev docs #3333

Fixes in dev docs #3333

grobmeier commented Dec 26, 2024

vy Dec 28, 2024

grobmeier Dec 28, 2024

ppkarwasz Dec 29, 2024

vy Dec 29, 2024

jvz Dec 30, 2024

ppkarwasz Dec 29, 2024

ppkarwasz Dec 29, 2024

ppkarwasz Dec 29, 2024

ppkarwasz Dec 29, 2024

vy Dec 29, 2024

jvz Dec 30, 2024

jvz Dec 30, 2024

jvz Dec 30, 2024

jvz Dec 30, 2024

	A project's new release does not necessarily mean a new release of its XML schemas.
	A new project release does not necessarily mean a new release of its XML schemas.

	The logging _implementation_ is responsible for handling this object, and we consider it a design mistake to limit applications to logging ``Strings``.
	The logging _implementation_ is responsible for handling this object, and we consider it a design mistake to limit applications to logging ``String``s.

	CI automatically populates `out`-suffixed ones; you are not supposed to touch them.
	CI automatically populates `out`-suffixed branch names; you are not supposed to touch them.

	If you don't find the answer to your question, please consult the link:{logging-services-url}/support.html[the support page].
	If you don't find the answer to your question, please consult link:{logging-services-url}/support.html[the support page].

Fixes in dev docs #3333

Are you sure you want to change the base?

Fixes in dev docs #3333

Conversation

grobmeier commented Dec 26, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment