Documentation is way too difficult to understand

[robertmclaws]

Instead of one giant page that tries to throw all the documentation for all the different versions into one logical thing, would it be possible to create a ReadTheDocs account for this project, and have separate docs for each version? That way people can be sure that they are only reading documentation for the version they are using, and not trying to guess which classname still applies and which changed in the last update (Example: DbApi vs EntityFrameworkApi).

Thanks!

[chinadragon0515]

@advancedrei thanks for your suggestions, improvement of document is one of items in our TODO, but due to other high priorities items, we have not had a chance to do this yet.

We highly welcome and appreciate any contributions to the project includes document.

[robertmclaws]

I am currently in the process of revamping the entire documentation set. I'm using the exact same process and hosting service that the .NET Core team is using, although they are using a slightly different toolset to achieve the same results.

I'm migrating the existing content over now. You can track my progress at http://restier.readthedocs.io/en/latest/

Once I get the latest release documented, my goal will be to figure out how to document prior releases through ReadTheDocs' GitHub + Versioning integration. That way, people can flip between versions and see ONLY the code that applies to them.

I will be submitting issues over the next few days related to this that will point out inconsistencies in the documentation or the APIs themselves, so that you all can help me clarify things and get updates into the docs.

I hope to complete this process over the next week or so. I would very much appreciate any feedback you may have. Thanks!

[robertmclaws]

FYI, here's an example of what I'm trying to do, in terms of completeness.
Before: http://odata.github.io/RESTier/#02-03-Submit-Logic & http://odata.github.io/RESTier/#02-09-Customize-Submit
After: http://restier.readthedocs.io/en/latest/server/method-authorization/

When sample code will itself be fully documented, be copy-paste ready with proper "usings", and will also have unit tests with 100% code coverage.

[chinadragon0515]

@advancedrei thanks for your great help, we was thinking some framework like https://mongodb.github.io/node-mongodb-native/ this one before, but we did not get resource to work on this.

Regard to new framework,

1. We want to be able to add content to github.com/odata/RESTier gh-pages branch, and content will be auto popped up in odata.github.io/RESTier, and this is consistent with our other projects, also have the same way as code for people to contribute.
2. Been able to create new version easier, like in the next release, when user define the operations in Api class, we will not need user to define a special controller to route these operation again, it will be auto handled which simplify the operation support. And most other content will be same, so we expect all content will be auto pop for next release except some sections we have tag/flag/version to indicate it will be hidden or been replaced.

[robertmclaws]

No problem, glad I could help.

As I mentioned on another thread, what I'm looking for after my first weekend messing with this is just feedback on the overall end-user experience of the documentation (quality of writing, quality of organization, quality of samples, etc). The domain name is just a place for me to work right now. I have a fork of the RESTier project they are being checked into, and the reason I'm not using a gh-pages for that at the moment is that this framework requires a build process, which ReadTheDocs uses automatically. I commit the docs, and updates are compiled and deployed almost instantly.

I don't want to rock the boat on processes, and be a good OSS citizen. At the same time, I would just gently suggest that your team should not be married to your existing documentation processes, because they aren't producing vary usable results. The WebAPI and RESTier docs may be consistent, but they're consistently not very good.

I really think everyone will like this, please just keep an open mind and give it a chance. 😃

[chinadragon0515]

@advancedrei thanks

When I said consistent experience, I do not mean we all stay with bad experience, I mean

1. We want consistent experience for our product, and target is all will be in same structure, and RESTier can move to new structure first. It will require it not take too much to move from current document structure to new document structure. So project like Web Api can move to new structure too.
2. For contributions to document, we want to be a consistent way to contribute as the way to contribute to the code, which means contributors still can send pull request for document contribution.
3. For new document structure, we are OK with some additional build process as long as we can benefit to our consumers, but we expect this process will be simple and not take too much time, so it is easy for any contributor to build by themselves and preview of their contributions.

I am looking forward to talk with you, and I worked with Mark.

[robertmclaws]

Awesome. :) We can totally achieve those goals. You can follow along with my repo here as I'm evolving the docs, so you can see how easy it is to contribute.

[chinadragon0515]

@advancedrei As you are working on a PR for this issue now, I assign the issue to you now, if you do not have time to continue the PR, let us know, and we will take over what you have.

[robertmclaws]

Awesome, thanks! I still have plenty of time, will be looking at another round of revisions in a few days.

[chinadragon0515]

One related discussion on document of odata .net lib is OData/odata.net#624

[chinadragon0515]

For existing document, I have separated it based on version starting from v0.6, you can refer to http://odata.github.io/RESTier/, http://odata.github.io/RESTier/v0.6/ and http://odata.github.io/RESTier/v0.5 to have a preview, and no plan to separate document of version 0.5 or earlier release. And starting from v0.6, only content for this version will be kept.

Let me know if you have any more comments.

In the meanwhile, Mark is still helping to work out the new host for the document.

[robertmclaws]

Covered in #643.