On the tooling side, there haven't been any significant changes since the discussions from last year. I'm only aware of a few small tweaks to the markdown output.
However, the Swift Package Manager documentation now publishes the documentation for all its commands and subcommands based on this output (AFAIK).
So, while the priority of this project idea is largely the same as last year, there is now a key tool in the Swift ecosystem that publishes documentation about its command line interface based on this output. This means that any improvements that you do would be reflected on those pages.
My recommendations specifically for scoping a project like this—where there isn't a single larger feature or enhancement to implement—would be to pick and choose a combination of different improvements that you each think provide some value in a way that also makes sense, or "tell a cohesive story", in aggregate.
That has the benefit that you can more easily make incremental improvements and that it's easier to rescope if you find that it's going either faster or slower than what you initially expected/planned.
If you think about the benefits that you want to accomplish and work your way backwards to how to accomplish that then this can also make it easier to write up a proposal because you'll have more concrete goals to write about.
Another aspect to consider is your own learning for example by asking yourself "what do I want to have learnt after this?". Being aware of what you want to learn can help you identify which improvements you would find most motivating to work on and influence your pick of improvements.
One way to go about making this a bit more concrete—to have somewhere to start—could be to look at of the Swift Package command pages (for example the add-dependency subcommand and compare that to the corresponding help text. From this you can both note a number of differences; to name a few:
- the page lists a large number of flags that the help text doesn't
- the pages doesn't separate arguments and options into groups
- flags like
--typeneither display their possible/allow values nor the default value
and you can try to ask yourself the question "what would I want to improve about this page"
Unfortunately that specific command doesn't organize its arguments and options into named groups so it can be useful to look at other tools and other commands as well to get a broader picture of the current state of the output and the possible improvements.
When it comes to knowing what improvements can be made in
- the markdown alone
- the markdown with generic symbol data
- the markdown with custom symbol data
my top recommendation would be to ask if you're unsure.
For changes that you think could or couldn't be made to the markdown output alone you can also experiment by editing the markdown by hand and seeing how it renders. For example; you can include the --type options's possible/allowed values and its default value as text somewhere in its description and see if you find a location and formatting that you like.
For the differences between what could be accomplished with generic symbol data compared to custom symbol data I recently listed a few examples (in this post) about some of the things that structure symbol data could do for command line documentation.
If you have any questions about that or anything else, don't hesitate to ask.
Yes, if you can share a draft and get feedback on it that allows you to iterate on your proposal before submitting it.