Huge problems with moving documentation

[tveito]

Again I see that the documentation have moved, and all previous links are again invalidated. This is a big problem for our company as we are creating guides for using pycom devices together with our services. Having to change out all the links in all our guides regularly is a huge problem as the guides will a lot of the time be wrong. I do understand the need from time to time to change the layout of a fairly new website, but what I can not understand is why all the previous links are not redirected to the new URI. If this had happened once or maybe even twice, it would be fine, but I feel like this is happening ever other week lately. With several hundreds of units and a lot of users, we do need to have our own, more detailed tutorials for using the services we provide. But when it comes to links to firmware or information that are documented on your site, it should be possible to have links to your documentation. Redirecting invalid links should take you about 10 minutes and save your users and customers hours.

Tveito

[bucknall]

Hi @tveito,

This is the only time that the links to the documentation will have changed.

We have never migrated the docs previously and are using the new platform permanently going forward.

If you can drop me an email at alex@pycom.io, I'm happy to work with you to ensure we can get your docs links fixed. I'm also discussing how we can, internally, work to re-validate the broken links.

Kind Regards,

Alex

[tveito]

@bucknall Well... that held for about a year... Today all the links are again broken. This makes it quite hard to maintain tutorials for your products without creating all the documentation necessary and urging the users not to upgrade their devices...

[Sympatron]

@bucknall I had problems with this too today.
I think it would be a very good idea to redirect with status 301 to the corresponding new page.
Otherwise all links in external documentation, the forum and even google are broken.

It doesn't even seem that hard to do for most of the documentation:

docs.pycom.io/chapter/firmwareapi/*
became
docs.pycom.io/firmware-and-api-reference/*

docs.pycom.io/chapter/tutorials/*
became
docs.pycom.io/tutorials-and-examples/*

[dan]

Hi @tveito and @Sympatron,

In a year, a lot of things change. We are using GitBook for our documentation and they are no longer supporting the older version that we were using, meaning that bugs won't be fixed and there will be issues in the future. The new version has a cleaner layout and improved features (we can link to headings, have better search, etc).

I understand that this might cause some inconvenience. I have restored the section links to match the old docs' links. However, the /chapter is still gone, but if you remove it from the old links, you'll get to the correct page. Google will re-index the pages in a few days. Please let me know if you find pages that are still broken, I'll fix it asap.

[Sympatron]

@dan But ALL links posted in this forums or other in the past will be invalid. I understand that you have to change things now and then. But invalidating all links is quite bad in my opinion if you could just redirect them to the corresponding new pages, which would not be that difficult to do since you basically just removed the /chapter prefix.

Showing a 404 and redirecting to the front page feels kind of a broken and not well maintained.

[philwilkinson]

@dan said in Huge problems with moving documentation:

Hi @tveito and @Sympatron,

In a year, a lot of things change. We are using GitBook for our documentation and they are no longer supporting the older version that we were using, meaning that bugs won't be fixed and there will be issues in the future. The new version has a cleaner layout and improved features (we can link to headings, have better search, etc).

I understand that this might cause some inconvenience. I have restored the section links to match the old docs' links. However, the /chapter is still gone, but if you remove it from the old links, you'll get to the correct page. Google will re-index the pages in a few days. Please let me know if you find pages that are still broken, I'll fix it asap.

Dan, the problems caused by this change are significant.
Did anyone think through the impact to users, particularly beginners?

Google will re index. Really ?
Please try a few google searches for Pycom product information and every single link will still return page not found. All the pinouts, tutorials, and API info.

Then try searching using the internal GitBook search, and there is very little identified there also.

[Tsvetelin]

@philwilkinson said in Huge problems with moving documentation:

Same here, i needed to access the GPy specsheet but it's impossible. Only the expansion board pinout and datasheet is available.

[dan]

@tsvetelin It's right here: https://docs.pycom.io/datasheets/development/gpy

[dan]

@philwilkinson We have triggered reindexing with Google, it's still ongoing. Please be patient, while we are working on it. In the meantime, you can specify which site you'd like to search on with the site: tag in your query.

I'm working on a assets resource, to separate it from the docs, so we can link to the datasheets, pinouts, etc directly. This would prevent this issue happening again.

Could you give me an example for an issue with the GitBook search? I'm in contact with them as well, if it indeed doesn't work, I can relay it to them.

[dan]

@sympatron Unfortunately, we can't rewrite the URL since we're not hosting it.

[Sympatron]

@dan I have no experience with GitBook, but it seems to support plugins and there are redirect plugins.

[dan]

@sympatron that's the legacy version. They have announced their own platform, which doesn't support plugins anymore, only a few of them that are now "first-class features".

[Sympatron]

@dan That's unfortunate...

I still think it is bad practice. Microsoft does this all the time with their documentation and it's infuriating to be redirected to the front page when you know the answer is somewhere but you can't find it anymore because you can't expect the average user to know your renaming scheme...

[dan]

Hi @sympatron,

After talking to support, I've set up redirects to the new URLs from the old ones. There might be still some links that are broken (we have a lot of pages and these redirects have to be set up one-by-one), if you or anyone finds one, just send me a message.

[Sympatron]

Hi @dan,

Just tested it for some pages and it works. Thank you very much!

Side node: Since you renamed your pages the docs only show in google if you add site:docs.pycom.io.