Restructure documentation

[ReubenBond]

.NET Rocks Ep 1338 - Akka.NET 1.1 with Aaron Stannard reminded me of a conversation I've had with several people recently about on-premise deployment in Orleans. People are confused about it and that's our problem.

We should have a clearly defined deployment section in the docs.

Generally speaking, the documentation should be rearranged. I took some inspiration from the ASP.NET Docs & had a first pass at it.

• Introduction
  • Orleans and the Virtual Actor model
  • Comparison to Other Systems
  • Installation - NuGet Packages (thanks, @richorama)
• Getting Started - very basic tutorial (see asp.net docs)
• Development (called Fundamentals in ASP.NET docs)
  • Grains
  • Grain Lifecycle (methods + the Application Garbage Collection page)
  • Handling Failures
    • try/catch
    • Multiple Activations
  • Stateless Workers
  • Clients
  • Servers (Silos)
  • Storage
  • Simple Grain Persistence
  • Manual Grain Persistence (using databases, etc, within Orleans - people want assurance that this is ok, so we should provide guidance/sample)
  • Developing Storage Providers
  • Timers & Reminders
  • Observers
  • Streams
  • ... all the streams content ...
  • Configuration & Startup
  • Dependency Injection
  • Bootstrap Providers
  • Serialization
  • Immutable (We could omit this here and leave it in the Performance section - it's a performance feature)
  • Interceptors & Hooks (Client, Silo, Grain, Bootstrap? Lifecycle? DI?)
  • Logging & Monitoring
  • Concurrency & Threading
  • [Reentrant] and concurrency control
  • Handling long-running or blocking code within Grain calls.
• Testing
  • Unit Testing
• Deployment (and providers)
  • Local Cluster (for development & testing only)
  • On-premise
  • Azure Cloud Services
  • Azure Web Apps
  • YAMS
  • Service Fabric
  • Consul
  • SQL Server
  • Geo-distributed Clusters
  • Changes to the storage model, etc
  • ... other cloud service providers ...
• Patterns & Best Practices
  • Smart Cache & other patterns from OrleansContrib/DesignPatterns
  • Best Practices
• Migration
• Performance
  • Configuring the .NET Garbage Collector
  • Selecting the right level of granularity for grains
  • Optimize copying using Immutable<T>/[Immutable]
• Troubleshooting
• Tutorials, Samples, Presentations, & Articles
• Internals (was Runtime Implementation Details)
• Contribute
• API Reference

Is there anything you would change about this structure? Maybe a patterns section? Help wanted :)

[gabikliot]

I like parts of your suggestion, but what confuses me (in the current docs as well), is the duplication between Tutorials and Development. What goes into Tutorials if all concepts are described in Development?

Also, what about Advanced concepts? There are a lot of things you don't want to throw on people as they start learning the basics. Like complex async patterns with Thread Pool and external scheduler. Where does this go?

[ReubenBond]

Good point, @gabikliot. Maybe the async/etc comments belong in a Best Practices section.

Tutorials are all self-contained and complete, but perhaps they should be moved to the bottom under a section with Tutorials, Videos, & Articles.

Would that be better?

There's no obvious way to know if something is advanced or basic. Currently the Advanced Concepts section is a grab-bag of so many things, eg: monitoring, timers & reminders, powershell, "garbage collection" (a term we should stop using - grains are never garbage), deployment to Azure Web Apps, Immutable, Serialization. At the very least, those entries need to be re-sorted.

EDIT: I updated the table of contents

[ashkan-saeedi-mazdeh]

@ReubenBond I think your suggestions make sense Reuben a lot , my 2 cents here. 1- We should talk about failure handling as well (maybe you forgot to list, I did an initial attempt which is in step by step tutorials) 2- I agree with Gabbi about tutorials and development guide, however I think everything and everything should be included in development guide, all conceptual information should be there and I should not go to step-by-step tutorials for any reason other than the desire to follow a tutorial.

Also we should add a reference. There are things which are not included like all variations of GetGrain and ClassPrefixNames and making different front-ends and more details about making membership providers and ... as ell , I could go on but instead let's create a plan of actions and start doing it :)

[ReubenBond]

@ashkan-saeedi-mazdeh I added API Reference to the bottom and Handling Failures under Grains. I've moved the tutorials to a section designed for links to tutorials, presentations and articles

[sergeybykov]

I like this very much. I think we can try to break the Advanced Concepts section into smaller better focused ones: Performance is already there, maybe Concurrency & Threading to encapsulate a number of topics, Integration with other frameworks and libraries, etc.

[richorama]

Looks good.

Have you intentionally removed the 'installation' section? I think this is quite a useful part of the docs, particularly the nuget packages page.

[ReubenBond]

@richorama it wasn't intentional - I've added it back. Thanks for pointing that out @sergeybykov I renamed the section on Reentrancy to Concurrency & Threading and moved [Reentrant] underneath it. Thanks

[ashkan-saeedi-mazdeh]

@ReubenBond Why I can not see your changes? neither the API reference nor the change of advanced concepts. Are you doing it in another branch/fork? I opened http://dotnet.github.io/orleans and they were not there.

[ReubenBond]

@ashkan-saeedi-mazdeh I am editing the original post. This is just an outline of the intended changes rather than a PR. It's a request for comments (and hopefully commits)

[ashkan-saeedi-mazdeh]

@ReubenBond Aha, Since you said "I added ..." "I did" ... I thought you are doing some of these. Hopefully I'll find time and do some of it.

[chris-eaton]

Hi...

Improving the docs is a great idea, if it helps heres a few comments

• Docs can be confusing, sometimes the navigation on the left changes unexpectedly making it hard to get back out or realise where you are.
• Akka.net docs seem to progress in a really nice linear way, taking inspiration from them is a good idea
• The tutorials make assumptions as to what you know or dont know that, as a beginner, makes it hard to understand. For example what nuget package do I install for each project? Whats the full source code for that tutorial?

[moswald]

The new Stack Overflow Docs stuff is really nice. Moving there may solve a lot of issues people have with the current documentation, as well as bring things in line with what Microsoft is currently aiming for (they are one of the major backers of SO Docs).

[ashkan-saeedi-mazdeh]

@moswald Your tag on SO needs to have certain reputation before you can create a docs site there. By their definition and in reality as well, we are still a not so popular technology.

@chris-eaton Awesome man! I hope we can create a good doc story as what Reuben suggested above and put it in place soon. For me, As soon as I finish my CouchBase provider for Orleans, I'll put my OSS time on the Orleans docs.

[richorama]

I have started work on this (this may take some time...):

https://richorama.github.io/orleans/Documentation/Introduction/Introduction.html

https://github.com/richorama/orleans/tree/gh-pages

[ReubenBond]

I think we don't need to track this anymore - the original proposal here has been superseded, anyway, so this issue doesn't serve much purpose.