[docs] organization, style, and grammar updates

[heckj]

Motivation:

Review of content against docs style guides for upcoming 1.0 release

Modifications:

• adds in default docs curation for the public types and articles
• rework language for Apple style guide as well as active voice, present tense, and American english spelling choices. Fixes some typos as well.
• shifting content into getting started, revising descriptions, removing passive voice
• manually linking to metrics API (hosted at SPI)

Before:

   --- Experimental coverage output enabled. ---
                | Abstract        | Curated         | Code Listing
Types           | 100% (2/2)      | 50% (1/2)       | 50% (1/2)
Members         | 100% (6/6)      | 0.0% (0/6)      | 0.0% (0/6)
Globals         | 100% (1/1)      | 100% (1/1)      | 100% (1/1)

After:

   --- Experimental coverage output enabled. ---
                | Abstract        | Curated         | Code Listing
Types           | 100% (2/2)      | 100% (2/2)      | 50% (1/2)
Members         | 100% (6/6)      | 100% (6/6)      | 0.0% (0/6)
Globals         | 100% (1/1)      | 100% (1/1)      | 0.0% (0/1)

To quickly preview locally:

gh pr checkout 81
swift package add-dependency https://github.com/swiftlang/swift-docc-plugin --from 1.0.0
swift package --disable-sandbox preview-documentation --target SystemMetrics

ex:

Biggest notable change that you we may not want to run with - I trimmed down what was at the top level, shifting away from the format that swift-configuration used, because that information felt overwhelming (it felt like a giant README trying to shove too much in there), and moved the getting started into a concise article that I curated inline.

I haven't added, but could, a quick walk through article with image snapshots w/ Examples/ServiceIntegration to show setting it up and seeing the metrics being reported in a local grafana instance, although I think the README in that directory is already pretty darned good and gets to the core for someone who just wants to see it work to get a sense of what's included.

[czechboy0]

Thanks @heckj, added a few more suggestions

[czechboy0]

I've been meaning to ask - what's the docc command to generate these? Or did you hand-write them?

[heckj]

lol - I hand wrote these. There's not a DocC command to generate them one off, unfortunately- I've just got 'my pattern' of how I do it, which it mostly stub, see what show's up in preview, then iterate to drop the right pieces into place.

That said, there is a curation generation command - although I'm not certain if anyone actually uses it, as it's not detailed anywhere in the docs. The gist of which is:

• create/get the symbols for the target/module
• use docc process-catalog to emit a default catalog

mkdir .symbolgraphs
xcrun swift build --target MyProjectExample \
  -Xswiftc -emit-symbol-graph \
  -Xswiftc -emit-symbol-graph-dir \
  -Xswiftc .symbolgraphs
mkdir Sources/MyProjectExample/Documentation.docc

# better generation using --from-symbol
# which constrains the generated content to MyProjectExample
xcrun docc process-catalog \
  emit-generated-curation \
  Sources/MyProjectExample/Documentation.docc \
  --from-symbol MyProjectExample \
  --additional-symbol-graph-dir .symbolgraphs

So it's kind of a pain to use...

[czechboy0]

Suggested change

	### Monitor system metrics
	### Essentials

I think "Essentials" is the usual name of the first section.

[heckj]

We see it commonly, but at least in the broader API guides, the last guidance I got here was essentials was meant to be "the things you critically had to know to be able to use the API", which I took as a placeholder to mean explanatory content prefixed into the getting started pieces when needed. This didn't quite seem to hit that bar for me, so I leaned into just giving a functional heading that made it reinforced what this was doing, especially since this is just a simple API surface.

[czechboy0]

Yeah that's fair - though I'd argue if you don't learn the SystemMetricMonitor API, then there isn't much you can do with the library. So IMO it does raise to the bar of being essential.

[czechboy0]

I think we should preserve the short code snippet, including the dependency snippets, here as well. We try to do that in most of our other packages, as that's what most people landing on this page want to see. We should still preserve the new, more detailed getting started guide, though.

So, I think this should show up on this page (the least customized way to run a system metrics monitor):

import SystemMetrics
import ServiceLifecycle
import Metrics
import Logging

@main
struct Application {
    static func main() async throws {
        let logger = Logger(label: "Application")
        let metrics = MyMetricsBackendImplementation()
        MetricsSystem.bootstrap(metrics)

        let service = FooService()
        let systemMetricsMonitor = SystemMetricsMonitor(logger: logger)

        let serviceGroup = ServiceGroup(
            services: [service, systemMetricsMonitor],
            gracefulShutdownSignals: [.sigint],
            cancellationSignals: [.sigterm],
            logger: logger
        )

        try await serviceGroup.run()
    }
}

[czechboy0]

Let's add the metrics factory here as well to avoid confusion about where the metrics go, so:

import SystemMetrics
import ServiceLifecycle
import Metrics
import Logging

@main
struct Application {
    static func main() async throws {
        let logger = Logger(label: "Application")
        let metrics = MyMetricsBackendImplementation()
        MetricsSystem.bootstrap(metrics)

        let service = FooService()
        let systemMetricsMonitor = SystemMetricsMonitor(logger: logger)

        let serviceGroup = ServiceGroup(
            services: [service, systemMetricsMonitor],
            gracefulShutdownSignals: [.sigint],
            cancellationSignals: [.sigterm],
            logger: logger
        )

        try await serviceGroup.run()
    }
}

[heckj]

Added in a follow on PR, but this example (which I copy-pasted) isn't using the factory initializer - wasn't 100% sure what that looked like, and honestly if we wanted to promote that path or not. I expect that anything in the README will be the first thing to be copy/pasted into place as an example that gets modified - so I think whatever we expect to be most commonly used would be best here.

[kukushechkin]

@czechboy0 do you suggest we change example to use SystemMetricsMonitor(metricsFactory:logger:)?

[czechboy0]

I think we should show the simplest one in the README, so the one without the factory parameter. Customizing the metrics factory is a slightly more advanced use case.

[kukushechkin]

Thank you for these improvements and explaining the reasoning behind it.

[kukushechkin]

With a max window width the reported label is split into two lines, making it hard to read the label. Can a thing inside the ticks marked to be rendered without line breaks?

[czechboy0]

We can maybe move the constants into a nested bullet point under each metric? That way they'll always start on the same column.