Re: improving API docs and tutorials user experience
+1 on auto-search inside 404 page. (btw, love the fixed version switch. So helpful). On 9/21/18, 2:50 PM, "Aaron Markham" 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 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" 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
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 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" 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
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" 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
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
