Orleans: Orleans Documentation - upgrade to a better documentation infrastructure

[shayhatsor]

The current documentation infrastructure lacks many desired features, for example:

• Tree structure
• Search/Filter
• Fluent navigation
• "Improve this doc" button

I think that DocFX can be the solution. It's the doc infra of .NET Core.
The purpose of this issue is to gather ideas and suggestions.
/cc @sergeybykov @jdom @gabikliot @jthelin @veikkoeeva @richorama @galvesribeiro

[richorama]

I like the idea of using DocFX.

I think it would allow us to keep the documents (if we want to) in the gh-pages branch, and use the existing http://dotnet.github.io/orleans url (at least for the root).

The search is quite interesting, it seems to maintain a search index as a json file, which it delivers down to the browser. The whole site can therefore be delivered as a static website.

I'm going to try hacking around with our existing content.

[shayhatsor]

@ashkan-saeedi-mazdeh, I believe this issue is the first step towards improving the documentation system and content. I totally agree with your comments on gitter, and your help is very much appreciated.

[ashkan-saeedi-mazdeh]

@shayhatsor I'm going to try to read some angular docs as suggested by @galvesribeiro and will start helping when time allows.

[jthelin]

+1 to adding auto-generated API docs for the public developer-facing APIs to the web site too.
cough aka javadocs cough ;)
That is one of the major things missing on the Orleans project website currently.

We originally used to use Sandcastle internally to generate Orleans C# API docs in .chm format [and then manually upload the .chm binary to the repo], but that tool / process was so hard to use it was practically impossible and not an experience i would ever wish to inflict on another living soul! :(

[shayhatsor]

@jthelin, I know what you're saying... we were using Sandcastle to generate API docs as part of the build process. Bad idea, there were many weird limitations, my favorite limitation was that you have to have a least one public class or it fails the build 😞

[gabikliot]

https://github.com/dotnet/orleans/issues/88

[sergeybykov]

@gabikliot Full circle. :-)

[richorama]

I have had a play with DocFX, and managed to get some of the content rendering:

This is just a naive setup, so it's far from complete, but shows it is possible.

The site will probably require some restructuring, but I think the bulk of the content can remain the same.

I think the advantages of using DocFX are:

• Nice stylesheet and page template
• Some built-in search capability (although that's not currently working for me)
• Consistent look with other .NET projects

The disadvantages:

• Incompatible with Jekyll, which gh-pages supports out of the box, so will require either manually running the build (type docfx on the prompt) or building on the CI server.

I also tried running docfx on ubuntu using mono, and it worked (or am I the only one who cares about x-plat??).

Do we want to proceed with DocFX, or keep with Jekyll?

Either way, I'd be happy to work on improving the docs.

[galvesribeiro]

@richorama nice!

I mentioned on Gitter that there is a "new MSDN" on the block(maybe it is based on DocFx? who knows!): https://docs.microsoft.com/en-us/dotnet/

This new docs engine from MS support GH, easy to edit, and Azure and .Net teams are using. I think someone can ping internally and check how to get us there. Would be nice tho have the "same experience" as all the other MS stack.

@sergeybykov can you check on that? I think worth try.

[sergeybykov]

I sent an email to people that might know.

[sergeybykov]

@richorama This looks so much more professional! Do you have an idea of what might be the issue with search? That's the biggest feature we are missing today.

[richorama]

I haven't looked into it yet. Leave it with me and I'll try and get something up and running.

Sent from my iPhone

On 30 Jun 2016, at 20:10, Sergey Bykov [email protected] wrote:

@richorama This looks so much more professional! Do you have an idea of what might be the issue with search? That's the biggest feature we are missing today.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.

[shayhatsor]

@galvesribeiro, the "new MSDN" is based on DocFX. https://github.com/dotnet/core-docs/blob/master/CONTRIBUTING.md#building-the-docs

[galvesribeiro]

good! so @richorama efforts are on the right way :) just need @sergeybykov to find out how we join the main docs site.

[ashkan-saeedi-mazdeh]

Guys since I'm doing a real project for the first time with Orleans and my Erlang experience is limited to small projects as well. I'm adding stuff to current docs so for example created a PR today. I hope this is ok until we change the infrastructure.

Also probably I'll be able to come up with a good narrative like documentation. Current material is very good but some stuff are hidden and finding them at the right time is not easy and this is bad.

[shayhatsor]

@ashkan-saeedi-mazdeh, this issue is by no means a blocker for improving the documentation content. DocFX plays well with our current content notation, so any improvement is welcome.

[shayhatsor]

implemented in #1970 by the awesome @richorama.