-
Notifications
You must be signed in to change notification settings - Fork 2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Split developer guide up into multiple pages #2700
Conversation
Put developer documentation into seperate pages
Test is failing because I need to update _includes/references.md with the location of the new links. I'll get on that shortly. |
Fix references and make tests pass
Fix broken links
Another benefit I forgot to mention: splitting up the pages allows us with analytics to see which sections of the developer guide are getting the most traffic. Like, if we notice that the mining guide is being read much more than the blockchain guide, we can prioritise that for update/translation. |
@Cobra-Bitcoin Thanks a bunch for working on this. We should consider adding automatic redirects instead of stubs for the old links w/ page anchors so that we don't lose our page ranking from before. Also, there may be links on other websites pointing to the anchors and redirects will smoothly transition visitors. This can be done starting on line 51 in Also, further down in |
Google will always see the developer guide page as one page (https://bitcoin.org/en/developer-guide), since that's how it's always been. The current Javascript redirect solution is pretty smooth. We can't redirect the entire developer-guide page itself though, since there's nowhere appropriate to redirect too, so having stubs will at least preserve the page in search engine results. Realistically the only way you can do redirects with page anchors is with Javascript, since everything else interprets URLs like "https://bitcoin.org/en/developer-guide#getwork-rpc" and "https://bitcoin.org/en/developer-guide#distributing-only-wallets" as being the same. The devsearch stuff is all linking to the developer reference, which we don't touch in this pull request. I thought to split up the developer reference another time based on feedback and lessons learned in breaking up the developer guide. |
Thanks for the additional context and clarification. Agreed it would be great to realize the additional SEO benefits for having the indexable pages, but maybe there's something more we can do to improve the UX of the modified developer guide homepage before merging: Maybe there is a way we can maintain the current UX (https://bitcoin.org/en/developer-guide), where users wouldn't have to scroll through the messages telling them the pages have moved, and still be able to see everything on one page? I'm concerned otherwise that the updated page may be more difficult and confusing to navigate for the user - the intro text is missing and the person that is reading through the sections is going to need to press the back button every time he/she wants to go to a new section. Just to reiterate, though, yes, it would be nice if we could realize the SEO benefit of the individual, indexable subpages. Just wondering how we can do that without sacrificing UX. |
I see what you mean, I'll work on something to make the UX better. The scrolling is annoying, I wasn't thinking too much about the UX. I have an idea on how to make it better. |
Ok, cool, thanks. |
Improve UX/UI of developer guide page
Fixes issue with subhead links missing to make tests pass
@Cobra-Bitcoin Thanks, this looks really nice. This is scheduled to be merged on Wednesday, October 31st. |
This change significantly improves the usability of the developer guide by breaking it up into multiple pages. The developer guide was becoming unwieldy, it's essentially one giant page and requires endless scrolling to get through. This also makes it difficult to begin translating it into different languages, since we would need to translate all the sections at once (we can't have the document half translated go live). SEO is also actively harmed because it's not possible to make the page optimized for certain keywords. We have comprehensive guides for the block chain and transactions, but when you search "blockchain guide" or "transactions guide", the page doesn't rank as well as it should. I've also made minor modifications to the guide, just to have content match the rest of the site when its shown on its own page.
This pull request splits each of the sections of the developer guide into its own page, here are some examples of how the pages are renamed. "https://bitcoin.org/en/developer-guide#block-chain" would become "https://bitcoin.org/en/blockchain-guide", "https://bitcoin.org/en/developer-guide#mining" would become "https://bitcoin.org/en/mining-guide", and so on for the other sections in the developer guide. The existing developer guide page would display a stub to inform the user that the content has been moved.
There are many links to numerous subsections of the developer guide, and we don't want to break these links, so I've made these old links automatically redirect to their newer versions. For example if a user clicks on a link like "https://bitcoin.org/en/developer-guide#getwork-rpc", their browser will redirect them to "https://bitcoin.org/en/mining-guide#getwork-rpc" if JS is enabled.
After this change, we'll have 8 new pages, full of content and with optimized keywords. It'll be a lot easier for users to navigate through the developer guide and share parts with others. We'll also set ourselves up to be in a good position to begin translation efforts and to update outdated parts (I noticed a few things that need updating that I'll take care of).