Provide a FAQ

[bgulanowski]

I have tried very hide to find a simple introduction to OmniSharp, with no luck. This is frustrating.

The project needs at least a FAQ, but ideally a full summary of what this thing is, why it exists, and how it works. From the README, these questions all seem to be taken for granted. READMEs should not assume any knowledge on the part of the reader. They should be useful to a curious person, even a fairly young and inexperienced. It should not be an immediate dive into obscure installation and configuration options.

Some example questions that a proper introduction or FAQ would answer:

What does the built application literally consist of? Is it an app? A service? A library? What is it called? How is it run? Is it always resident, or launched on-demand?

How does other software communicate with it?

How can one tell if it is working? How can it be tested at runtime? How can various features be verified?

What do you do if it isn't working properly? What kinds of things can go wrong? Where are the log files? How are errors reported?

What additional tools does it come with? What are they called? How are they used?

What user account does it run under?

How is it updated?

What are its dependencies?

What is the version history? How do you tell what version is running?

If there already is documentation, then it is not surfacing properly in web searches, and it is not linked from the README, which seems like a huge oversight.

[JoeRobich]

Took a quick try at answering these. Certainly they could all be more detailed.

1. What does the built application literally consist of? Is it an app? A service? A library? What is it called? How is it run? Is it always resident, or launched on-demand?

OmniSharp (O#) is a server application which provides C# language services (QuickInfo, Completion, Diagnostics, etc...). It is typically installed as part of C# language support in many popular code editors (VS Code, Emacs, VIM). It is run on-demand against a particular Solution file (.sln) or folder containing a C# Project file (.csproj) which we typically refer to as a workspace.

2. How does other software communicate with it?

OmniSharp supports its own O# protocol as well as LSP (when using the --lsp flag). There are separate builds which communicate over STDIO as well as HTTP.

3. How can one tell if it is working? How can it be tested at runtime? How can various features be verified?

OmniSharp reports errors via STDOUT and these are surfaced differently depending on your the code editor extension you are using.

4. What do you do if it isn't working properly? What kinds of things can go wrong? Where are the log files? How are errors reported?

Errors are reported via STDOUT. Typical failures are that a .NET SDK is not installed, the wrong version of the .NET SDK is installed, or the code being edited is not actually part of the workspace that O# was launched against.

5. What additional tools does it come with? What are they called? How are they used?

N/A

6. What user account does it run under?

This potentially differs depending on the code editor extension being used. Typically, I would expect it to be run under the user account which launched the editor.

7. How is it updated?

Release builds are available on GitHub. However, O# updates typically come with updates to the code editor extension being used.

8. What are its dependencies?

The .NET SDK will need to be installed and available from the $PATH.

9. What is the version history? How do you tell what version is running?

We track changes in our CHANGELOG. Currently there is not a command-line option to print the server version.