Orleans: Orleans Documentation Tech Writer

[JillHeaden]

Hi! My name is Jill Headen and I've been brought onto the Orleans team at Microsoft to improve the documentation for this project. I thought I'd start out by asking you what you want. Please feel free to send me suggestions, ideas, links, etc.
I'm in the process of setting up my development environment and getting some hands-on experience with Orleans, so if you have tips for me about that, please let me know.

Update:
As I work through the Documentation-tagged issues, I am going to compile general reminders for myself here, such as:

• add "last edited: 5 June 2018" information to the bottom of my edited pages.

[veikkoeeva]

@JillHeaden Just to drop a note that I can help at least with some ADO.NET issues. In case you need to ask something, ping in Gitter and someone will help.

[lfzm]

@JillHeaden welcome

[jan-johansson-mr]

Hi and welcome!

The current documentation is a good start, but of course need some correction and maybe somewhat easier content. The current documentation (in my opinion) miss out on introductory level and dives straight into technical details. My experience is that good technical writings pilots from high level and travels along a thread that eventually leads to the details needed for more advanced scenarios. And again I find that images/graphs are much easier to reason about than "a wall of text".

Orleans is an amazing solution, and one important ingredient to reach wider is to enable understanding of what it is, how to apply and of course what business value it brings to the table, both feature wise and what problems it solves.

BR,
Jan

[veikkoeeva]

@JillHeaden See discussion at https://gitter.im/dotnet/orleans?at=5b170c7d16f64961240d236f, a bit before too and then at https://gitter.im/dotnet/orleans?at=5b179b2fedd06f7d151353e5. Tagging @mlathan and @nockawa here too.

[nockawa]

Hello @JillHeaden , glad to hear that.
I can give few suggestions so far:

• Tutorials/Sample of the 1.5 version should be updated/copied to the 2.0 section, new users don't expect to look at previous version of the doc to find more content.
• More info about how to use other Database Providers would be nice (PostGreSQL, etc.)
• The Relational Storage page is outdated, links are broken...

[veikkoeeva]

To add here, the linked relational page seems really old. The newer sections are like https://dotnet.github.io/orleans/Documentation/Deployment-and-Operations/Configuration-Guide/Configuring-AdoNet-Providers.html .

[jan-johansson-mr]

I remember reading through the documents that @veikkoeeva references, and kind of experimenting a little before I got PostgreSQL working as store. Storage is important and I think that the documentation surely can be improved.

[jamescarter-le]

I could provide some documentation on Grain Services I added last year if you provide a preferred format.

[JillHeaden]

@jamescarter-le - Yes, please! I'm open to suggestion about this, but how about if you create an issue, name it something like "Grain Services Documentation Content", copy and paste whatever you have into there, and assign it to me? That could give others a chance to evaluate the technical content.

[dandago]

Welcome! As a former Orleans user, and a past and present Orleans supporter, I've been a strong proponent of better documentation for a couple of years now, so I'm really happy it's getting some extra help.

While I'm wary of plugging my own blog, I've written a few introductory articles on Orleans in the past (have a few more in the pipeline, but I'm struggling to find time to see them through at the moment) and some people have found them helpful. Perhaps you'll find some elements in there that may be useful to use for tutorials in the documentation.