Improve documentation

[matthewbastien]

Improvements to the documentation:

• Add documentation for the Documentation Live Preview feature
• Add folders to userdocs.docc to better structure it
• Add links to VS Code documentation where helpful
• Add an advanced article for installing the pre-release version of the extension
• Refer to VS Code consistently in all articles
• Refer to the Swift extension consistently in all articles
• Use the Dark (Visual Studio) theme for all screenshots

[tracymiranda]

Great to have more detailed docs!
The installing pre-release builds I believe is covered in the contributing.md - wonder if it's worth merging these improvements to that doc and referencing it?
The gifs are amazing!!!

[matthewbastien]

wonder if it's worth merging these improvements to that doc and referencing it?

I thought about that, but I think it's best to keep them separate. The contributing guide has more information that only contributors would need (e.g. version numbering information) while the userdocs are geared towards users of the Swift extension that probably don't care about those details.

The image is shared at least so that will be consistent between the two pages.

[heckj]

Lots of smaller wording suggestions and rewrites of phrasing to either be more direct or to remove the use of passive voice, which isn't as clear in terms of "who's doing what" when describing actions.

There's numerous places where you lead with a tip, talking about how some functionality is common across all extensions that I think you should consider reworking. You generally don't want to lead with a tip right at the top of an article, and all those tips provide a link away from the content you're about to present, so it reads as though you're saying "Go read this first!". I provided a few trials of other wording, but in general, I'd remove it as a callout (something with a big box around it) and work it into the first paragraph of the overview of those pages, including the link, but more subtly - just commenting that what you're about the detail below is common infrastructure for VSCode.

There were also some images that didn't have alt-text that really should - even if simple renditions, but it'll make a HUGE difference for folks with screen readers.

[matthewbastien]

Thank you for the very thorough review @heckj!