For macros, the new conceptual content will go in the guide in a new Macros chapter, following the existing Concurrency chapter. The high-level outline is as follows (for a detailed outline, see the work in progress linked below):
Intro: what's a macro?
Using a freestanding macro to produce a value
Applying an attached macro to a declaration
How macros are expanded
How to declare your own macros
How to implement a macro. This will highlight some of the most important APIs from SwiftSyntax and link there for more details.
Tips for debugging and developing macros, including guidance to use unit tests for your macros.
The reference will need a new section in Declarations for macro declarations, as well as updates in Attributes for @freestanding and @attached.
For parameter packs, the new conceptual content will go in the guide under a new section in the Generics chapter. The high-level outline is as follows (for a detailed outline, see the work in progress linked below):
Why parameter packs? To define APIs that vary in arity, without using type erasure.
How do you create a parameter pack?
How do you repeat more than one type?
How do you access the values of a parameter pack?
The reference will need updates in Expressions and Types.
This seems like a good start, but it would be clearer if terms like pack and expansion are defined and exemplified before they are used in rules. In general I think it would be helpful if the large number of new terms and concepts that are introduced with the parameter pack feature would be explained with examples instead of abstract descriptions, not just here but in pitches and proposals.
I think it will need to, because the approach and APIs you use for a freestanding vs attached macro are different. The discussion of creating macros can start with a freestanding macro, which I can show with an example that doesn't need to read the AST. That lets me show the code for declaring and defining a macro. Then a later example can show an attached macro, which does use the Swift Syntax APIs to read the AST.
In TSPL, it will certainly be the case that new terms are defined when they're first used. In the legacy RST pipeline, we even used special markup for "a new term is being introduced and defined here" — in markdown, it's just italics.
If you're meaning to give feedback about the Swift Evolution proposal, that's certainly welcome — but the authors of the proposal aren't necessarily reading this forum post, so this isn't the best place to share it. The definition I've been looking at for parameter packs is in SE-0393 in the list after "Here are the key concepts introduced by this proposal".