You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@mxnet.apache.org by Aaron Markham <aa...@gmail.com> on 2018/09/19 00:07:55 UTC
improving API docs and tutorials user experience
Hello dev list!
I've been doing a bit with .htaccess redirects on the site to get us things
like custom 404s and redirecting google searches that come in on outdated
material. That's working pretty well because the redirects are simple.
I need help though. I've written a short proposal on how I think the UX for
API docs and tutorials should work. I'm not trying a major jump here. This
is a small amount of change for a better experience.
For example, right now, if you're browsing API docs for 1.3.0 and want to
see the master version, you would hit the dropdown and select master. Then
you get taken to the home page for master and have to go find the document
again. (It's always done this.) It should stay on that document, but give
the latest version. Or for tutorials, if you request a really old, likely
broken tutorial because it happens to show up in google search results, the
site should kindly escort you to the latest, tested tutorial.
mod_rewrite and .htaccess can do this, but it requires regex skills that I
lack. I've tried hundreds of variations now, and would like some guidance.
Here's the proposal and my notes:
https://cwiki.apache.org/confluence/display/MXNET/Version+calls+and+redirects+for+Tutorials+and+API+documents
I appreciate your help with this!
Cheers,
Aaron
Re: improving API docs and tutorials user experience
Posted by "Afrooze, Sina" <si...@gmail.com>.
+1 on auto-search inside 404 page. (btw, love the fixed version switch. So helpful).
On 9/21/18, 2:50 PM, "Aaron Markham" <aa...@gmail.com> wrote:
I fixed the most annoying behavior with the versions dropdown here:
https://github.com/apache/incubator-mxnet/pull/12632
Now it'll remember what doc you're on when you switch versions.
I show an example with autograd where when you switch versions it keeps you
on topic even down to the bookmark. If you go to an old version where it
doesn't exist you get a custom 404.
I guess it could be possible to daisy chain some checks and redirects, but
this could be jarring.
I like this concept of suggestions though. What if the 404 page gets a
query string with a topic payload, and we use that to throw out some search
results?
On Thu, Sep 20, 2018 at 1:57 PM Afrooze, Sina <si...@gmail.com> wrote:
> This is not a fully baked idea, so bear with me. Instead of using regex,
> what if we use search techniques to locate the page user wants to look at.
> If I'm currently looking at mxnet.ndarray.convolution operator in master,
> take me to the same operator API in 1.2.1, regardless of whether it is in a
> similar page or whether we decided to re-organize API pages and create a
> page just for convolution. Likewise for tutorials (i.e. find the tutorial
> that best matches the content I'm looking at, even if it's been renamed or
> moved around). I feel like it can be a great internship project. - Sina
>
> On 9/18/18, 5:08 PM, "Aaron Markham" <aa...@gmail.com> wrote:
>
> Hello dev list!
>
> I've been doing a bit with .htaccess redirects on the site to get us
> things
> like custom 404s and redirecting google searches that come in on
> outdated
> material. That's working pretty well because the redirects are simple.
>
> I need help though. I've written a short proposal on how I think the
> UX for
> API docs and tutorials should work. I'm not trying a major jump here.
> This
> is a small amount of change for a better experience.
> For example, right now, if you're browsing API docs for 1.3.0 and want
> to
> see the master version, you would hit the dropdown and select master.
> Then
> you get taken to the home page for master and have to go find the
> document
> again. (It's always done this.) It should stay on that document, but
> give
> the latest version. Or for tutorials, if you request a really old,
> likely
> broken tutorial because it happens to show up in google search
> results, the
> site should kindly escort you to the latest, tested tutorial.
>
> mod_rewrite and .htaccess can do this, but it requires regex skills
> that I
> lack. I've tried hundreds of variations now, and would like some
> guidance.
>
> Here's the proposal and my notes:
>
> https://cwiki.apache.org/confluence/display/MXNET/Version+calls+and+redirects+for+Tutorials+and+API+documents
>
> I appreciate your help with this!
>
> Cheers,
> Aaron
>
>
>
>
Re: improving API docs and tutorials user experience
Posted by Aaron Markham <aa...@gmail.com>.
I fixed the most annoying behavior with the versions dropdown here:
https://github.com/apache/incubator-mxnet/pull/12632
Now it'll remember what doc you're on when you switch versions.
I show an example with autograd where when you switch versions it keeps you
on topic even down to the bookmark. If you go to an old version where it
doesn't exist you get a custom 404.
I guess it could be possible to daisy chain some checks and redirects, but
this could be jarring.
I like this concept of suggestions though. What if the 404 page gets a
query string with a topic payload, and we use that to throw out some search
results?
On Thu, Sep 20, 2018 at 1:57 PM Afrooze, Sina <si...@gmail.com> wrote:
> This is not a fully baked idea, so bear with me. Instead of using regex,
> what if we use search techniques to locate the page user wants to look at.
> If I'm currently looking at mxnet.ndarray.convolution operator in master,
> take me to the same operator API in 1.2.1, regardless of whether it is in a
> similar page or whether we decided to re-organize API pages and create a
> page just for convolution. Likewise for tutorials (i.e. find the tutorial
> that best matches the content I'm looking at, even if it's been renamed or
> moved around). I feel like it can be a great internship project. - Sina
>
> On 9/18/18, 5:08 PM, "Aaron Markham" <aa...@gmail.com> wrote:
>
> Hello dev list!
>
> I've been doing a bit with .htaccess redirects on the site to get us
> things
> like custom 404s and redirecting google searches that come in on
> outdated
> material. That's working pretty well because the redirects are simple.
>
> I need help though. I've written a short proposal on how I think the
> UX for
> API docs and tutorials should work. I'm not trying a major jump here.
> This
> is a small amount of change for a better experience.
> For example, right now, if you're browsing API docs for 1.3.0 and want
> to
> see the master version, you would hit the dropdown and select master.
> Then
> you get taken to the home page for master and have to go find the
> document
> again. (It's always done this.) It should stay on that document, but
> give
> the latest version. Or for tutorials, if you request a really old,
> likely
> broken tutorial because it happens to show up in google search
> results, the
> site should kindly escort you to the latest, tested tutorial.
>
> mod_rewrite and .htaccess can do this, but it requires regex skills
> that I
> lack. I've tried hundreds of variations now, and would like some
> guidance.
>
> Here's the proposal and my notes:
>
> https://cwiki.apache.org/confluence/display/MXNET/Version+calls+and+redirects+for+Tutorials+and+API+documents
>
> I appreciate your help with this!
>
> Cheers,
> Aaron
>
>
>
>
Re: improving API docs and tutorials user experience
Posted by "Afrooze, Sina" <si...@gmail.com>.
This is not a fully baked idea, so bear with me. Instead of using regex, what if we use search techniques to locate the page user wants to look at. If I'm currently looking at mxnet.ndarray.convolution operator in master, take me to the same operator API in 1.2.1, regardless of whether it is in a similar page or whether we decided to re-organize API pages and create a page just for convolution. Likewise for tutorials (i.e. find the tutorial that best matches the content I'm looking at, even if it's been renamed or moved around). I feel like it can be a great internship project. - Sina
On 9/18/18, 5:08 PM, "Aaron Markham" <aa...@gmail.com> wrote:
Hello dev list!
I've been doing a bit with .htaccess redirects on the site to get us things
like custom 404s and redirecting google searches that come in on outdated
material. That's working pretty well because the redirects are simple.
I need help though. I've written a short proposal on how I think the UX for
API docs and tutorials should work. I'm not trying a major jump here. This
is a small amount of change for a better experience.
For example, right now, if you're browsing API docs for 1.3.0 and want to
see the master version, you would hit the dropdown and select master. Then
you get taken to the home page for master and have to go find the document
again. (It's always done this.) It should stay on that document, but give
the latest version. Or for tutorials, if you request a really old, likely
broken tutorial because it happens to show up in google search results, the
site should kindly escort you to the latest, tested tutorial.
mod_rewrite and .htaccess can do this, but it requires regex skills that I
lack. I've tried hundreds of variations now, and would like some guidance.
Here's the proposal and my notes:
https://cwiki.apache.org/confluence/display/MXNET/Version+calls+and+redirects+for+Tutorials+and+API+documents
I appreciate your help with this!
Cheers,
Aaron