5 ms·

Great idea I especially appreciate the fact that its done by example. A couple of things that bothered me are: 1. The UI needs some refinement. I was looking t

Great idea I especially appreciate the fact that its done by example. A couple of things that bothered me are: 1. The UI needs some refinement. I was looking to find a topic to post about and from my 10 minute browse I realised that if I was meant to find information in this documentation it's really hard to find what you are looking for. After you drill down to a tag it feels "unstructured". Readthedocs layout feels more user-friendly. 2. To future proof the documentation examples should come with a version number they apply to. For example there is PayPal and DropBox API examples which in a few months might no longer be valid.

alex_hitchins 10y ago
Regards to no. 2 in your list, I was thinking something akin to MSDN, whereby one can change the version of the platform in question (Say MS SQL, .Net Framerwork)
progval 10y ago
Regarding #2: I noticed that in Python there are content blocks that can be marked specific to a version.
donny5 10y ago
#2 is actually implemented. Applicable versions are displayed on every page.
lucb1e 10y ago
The UI needs some big improvements indeed. I toyed around with the site and although I could find my way around when just clicking through some topics, I am still confused as to what the structure of the site is (other than a list of topics, with a list of examples, not hierarchically structured or Q&A style or anything else that would make sense). I'm not sure I could find anything on here if I didn't get there via Google already.
- eric_h 10y ago
  personally, google is how I always end up on stack overflow, so I'd imagine the same will be true for this product.
  - lucb1e 10y ago
    19 out of 20 times, true. However I totally get how SO is structured and contributing answers to people's question is something everyone gets. And if I want to find other questions (like for marking a duplicate, or researching a topic) I can use the search and tag system easily. Somehow the structure of this documentation area is not very clear to me.

alex_hitchins 10y ago

Regards to no. 2 in your list, I was thinking something akin to MSDN, whereby one can change the version of the platform in question (Say MS SQL, .Net Framerwork)

progval 10y ago

Regarding #2: I noticed that in Python there are content blocks that can be marked specific to a version.

donny5 10y ago

#2 is actually implemented. Applicable versions are displayed on every page.

lucb1e 10y ago

The UI needs some big improvements indeed. I toyed around with the site and although I could find my way around when just clicking through some topics, I am still confused as to what the structure of the site is (other than a list of topics, with a list of examples, not hierarchically structured or Q&A style or anything else that would make sense). I'm not sure I could find anything on here if I didn't get there via Google already.

eric_h 10y ago
personally, google is how I always end up on stack overflow, so I'd imagine the same will be true for this product.
- lucb1e 10y ago
  19 out of 20 times, true. However I totally get how SO is structured and contributing answers to people's question is something everyone gets. And if I want to find other questions (like for marking a duplicate, or researching a topic) I can use the search and tag system easily. Somehow the structure of this documentation area is not very clear to me.