Repository navigation
Improve Documentation #2497
Description
I wanted to give some feedback on my time using dart-code in vscode and particularly the startup experience.
So firstly great tool and I largely enjoy my time working with vscode and dart-tools.
So now the complaint :)
I came to dart-tools as a first time vscode user (long time eclipse user) and as such had no idea how either worked.
I would speculate that my startup experience is not an uncommon one.
The problem is that (and this is a problem with most vscode extensions) they expect you to know how to use vscode.
Of particular note is settings.
When I first started I hand no idea about the .vscode directory nor the launch.json or settings.json.
Much of the extension code says things like place 'fred.impoort.x=y' in your settings file.
Where is my settings file?
Once I found the settings file exactly where does it go in the settings file?
These type of assumptions make it quite hard to get up and running.
The other issues is the lack of documentation on the available settings.
Through my discussions with you I've discovered a number of useful settings.
It would be much better if there was a documented that described each setting and where to place them.
There also needs to be doco on the lauch.json configuration and flutter specific options.
Some of the issues that have been hard to find.
How to pass args to a launch.
How to use the 'console' option.
In another issue we have discussed the new --fast-start option.
Given the importance of this feature there should be doco on how to use it.
Activity
DanTup commentedon May 27, 2020
Thanks for the feedback!
This is definitely a concern I've had too. If you don't know how to use VS Code, that definitely makes it hard to use Dart-Code effectively.
However, a big question though, is how much should individual language extensions try to teach a user about VS Code? There would be a lot of duplicated effort if every extension tried to teach how VS Code works, and VS Code already has some very good docs.
Is it in the release notes where you've seen this most? When I started writing them, settings were also edited in the JSON file, but now the UI is the default, probably I should change how I describe these. Do you think if the mentions of settings (in the release notes / website) also linked to this page that would sufficiently help?
These are all shown in the VS Code user settings section with descriptions - is this something you've found and think could be improved, or is the issue that it is too hard to discover that they're listed here?
I very much agree with this. Over the last few weeks I've been thinking about how much of the details of these things are spread across release notes and not documented elsewhere (for example the upcoming release CodeLens templates are very powerful, but should be properly documented somewhere as a feature outside of the release notes).
For additional flags in Flutter like this, I tend to wait a while before deciding whether to add anything specific here. Flutter has a lot of flags and to expose them all in VS Code (eg. as settings) would be a lot of maintenance (especially as unlike the Flutter SDK, Dart-Code needs to behave correctly across many versions of the SDKs). Generally if something seems like an advanced option and is available with a simple flag, I would expect users that want to use it to add it to
argsin the launch config.I think we could have a simple page on the website (that's easy to find when searching) that explains how to set up common cases like this would be useful though. I also wonder whether we could add known strings to the completion list when editing the
argsin VS Code? I'll do some testing of that - I think it would aid discoverability a little.That said, for this one in particular, my assumption (which may or may not be correct) has been that when that feature is considered stable, it would become default (which would cause users to get it without needing to do anything).
I'll keep this issue open to work on the things above, and post notes/commits here for things that are changed. If you have additional feedback or comments please do keep it coming :-)
[-]Documentation improvements[/-][+]Improve Documentation[/+]DanTup commentedon May 27, 2020
We can include strings in the completion for
args, however I'm not sure if this makes it look like you can't enter your own arbitrary strings (you can, and that still validates)? 🤔bsutton commentedon May 28, 2020
So there are some balance points that need to be found.
I agree that we shouldn't be replicating the vscode documentation and in some instances it is probably appropriate to just put in a reference to the applicable section of the vscode document.
For this like setting I think we need to be explicit.
To me its a bit like find a code snippet on stack overflow and then don't include the imports statement. You then have to do a whole lot of work to get the code working.
Settings should state the file and section and probably have an example.
I should not that even after almost 12 months with vscode I wasn't aware of the settings page for dart-code. So I think it would be useful to detail this.
Agree completely.
Perhaps it could contain notes on passing flutter args on startup and a link to a flutter page that details the supported args (assuming one exists).
I think the auto complete for the args array is ok. I think most people will be aware they can add other strings.
DanTup commentedon Jul 28, 2020
I've beefed up a number of the docs pages on the websites, and added a couple more, such as:
Hopefully these will start to show up when searching the web with appropriate terms that should make it easier to find.
I'll close this issue, but do feel free to open new ones if you find things that aren't document (or not as well/clearly as you think they could be).
Thanks!