Consolidate Documentation

#1

Given that the documentation is basically the same for all SDKs - is it worth trying to consolidate it into a document that is similar to: https://stripe.com/docs/api

Perhaps using: https://github.com/lord/slate

W

3 Likes
#2

I think this could be really cool; It would make it easier to use and update the docs across multiple platforms.

Although, it would be quite a lot of work to do well - let’s see if there is significant interest / people willing to help.

#3

I love this!

I use the stripe sdk. I switch between php, node and curl quite a bit. It works very well.

For the parse sdk’s, the layout of both the php and javascript sdks are poor – the docs themselves I think are good, but hard to read because of the poor formatting/navigation.

i tried to fix the layout of javascript sdk, but couldn’t find one that worked well/better.

#4

Out of curiosity I have set up a sudo Parse Docs on a repo forked from Slate. I haven’t started adding content yet as I want to make sure there is significant interest/need for this but I have set it up to deploy to Github Pages so you can see the live site (very basic atm) and the repo.

Feel free to fork my repo and play around with it - please note that nothing is set in stone at the moment and there is no guarantee that this will go ahead.

If there is enough interest in this I think before proceeding it’s important for us to agree on what is bad about the layout/explanation etc of the existing docs so that we can try to rectify those issues in a new set of docs.

1 Like
#5

I love the idea of what the end product could look like.

What you’re suggesting is how Algolia and Stripe handle their guides which are both excellent in my opinion.

I think that it would be a big effort.

I use the cloud code, parse-server, js, and php guides regularly.

I probably refer to the api documentation a little more frequently than the guides.

I’ve added and edited the guides more often than I have edited the code comments that the api’s are generated from.

Personally I find the api documentation to be in much worse shape than the guides. The content of the API docs are pretty solid, but the navigation and formatting of the php and js api guides I find to be very difficult to use.

In the case of the JS docs, there is really no practical way to navigate the top level classes short of a using the browser search to try and find ‘object’ or ‘query’.

The php docs are somewhat better, but still very difficult to use with very unfortunate formatting.

1 Like