search

haskell-lang / haskell-lang

haskell-lang.org website
BSD 3-Clause "New" or "Revised" License
146 stars 73 forks source link

Finding relevant documentation via search engines is incredibly difficult #117

Open vbop9834 opened 7 years ago

vbop9834 commented 7 years ago

It is difficult to find relevant haskell documentation with search terms. This was briefly discussed on twitter https://twitter.com/Blaisorblade/status/825082970495135744

Fixing this would allow for newcomers to easily find information, enabling them to learn more about the Haskell ecosystem.

There are some SEO tricks that we can do to fix this. I'll come back to this issue tomorrow to fill it out further

  1. Remove dead/broken links. Dead/Broken links greatly reduce SEO ranking. We can use google analytics to see all the broken internal links (https://support.google.com/webmasters/answer/138752?hl=en) or some other tool.
  2. Add Metadata HTML metadata or JSON-LD metadata would help with indexing content https://support.google.com/webmasters/answer/79812?hl=en
  3. Add descriptions of content (Abstract or summary) in meta tag https://yoast.com/meta-descriptions/
  4. Add a sitemap (include out of date content with appropriate tags) https://support.google.com/webmasters/answer/156184?hl=en
  5. Add no-follow to external links https://support.google.com/webmasters/answer/96569?hl=en
  6. Add publish dates to content

This is a huge goal. Achieving this would greatly increased visibility and ease adoption of the Haskell language.

Blaisorblade commented 7 years ago

A note, since I suggested this bug tracker: the original discussion was about the GHC user manual, so I'm not sure this is the perfect place. But the mission of this project is making Haskell docs more accessible, so I guessed people here would be more open to such an issue.

What I have seen is that if I search info on some feature Google suggests typically some older version of the manual, rather than the latest one. The discussion suggested SEO could fix that. The Twitter thread has even better ideas, but some seemed lower effort.

snoyberg commented 7 years ago

I'm totally in favor of fixing this situation, I just highly doubt there's much we can do at haskell-lang.org. Even if we started hosting the GHC user manuals from this domain, with stable permalinks and a good sitemap, it won't guarantee in any way that Google will preferentially index us. (Though having that content on either this site or stackage.org does make a lot of sense to me. Even just uploading it to S3 could be a good thing.)

Any thoughts on just the local solution and trying to convince people to start linking to our locations?

vbop9834 commented 7 years ago

@snoyberg is correct. Hosting the ghc user manuals won't guarantee first page results.

Haskell-lang.org is a great option for storing relevant documentation for the haskell language. This is due to the keyword relation of the domain name. The search algorithms should favor haskell-lang.org due to the straightforward nature of the site content. As long as the general category of content on haskell-lang.org doesn't change then the pages should rank high due to relevancy.

Duplicate content will negatively impact SEO ranking. This include duplicated content from internal pages and external sites. Where we can innovate this is by creating content that enhances the user experience with the GHC user manuals and appropriately linking to it. Essentially this is creating a resource that interfaces with the user manual, providing the user with a better user experience. Search algorithms favor, above all else, positive user interactions which is measured via analytics metrics such as average page duration, amount of clicks, returning users, content interaction, pages iterated during session, etc..

The Proposal

We need volunteers to work on the following

The Problem

This is not sustainable. By doing this once and creating this resource, it will be required of the community to update it with each version. There are ways we can optimize this process to be more efficient. By demonstrating the utility of SEO in documentation, we can begin the conversation of creating an efficient system for documentation that provides a quality user experience. Achieving such a system outweighs any other SEO tricks.

Blaisorblade commented 7 years ago

I'm totally in favor of fixing this situation, I just highly doubt there's much we can do at haskell-lang.org.

To clarify: My idea was kind of

  1. establish there's a problem
  2. hash out actionable ideas to get started, especially low-hanging fruits
  3. file appropriate tickets in the appropriate places

Usually steps 1 and 2 would happen on a mailing list or the Haskell subreddit, but I suggested first a venue more friendly to this thinking. Does this make any sense?

My guess is that some things should be addressed by the GHC manual. And some things seemed to me low-effort enough to be doable. The thread started with:

Haskell websites are littered with broken links to old GHC manual pages because it doesn't maintain consistent URLs. Wow. that greatly reduces SEO ranking and should be fixed so ppl can find answers to their problems

So I thought they could maintain consistent URLs for things that remain stable (most of the manual I think)?

Other issues mentioned included:

vbop9834 commented 7 years ago

Broken links damage SEO ranking because it provides a bad user experience. The goal of search algorithms is to provide better search results by favoring overall user experience.

A custom google search will solve the problem of a searchable manual but will not solve the problem of increasing visibility of relevant documentation when using general search engines. We can focus on low-hanging fruits but we sacrifice the overall mission of SEO which is to increase find-ability for haskell resources.

Fixing 404's should be the first priority if possible. We can focus our efforts on haskell-lang.org and rank topics to relevant resources as an overall SEO strategy.

chris-martin commented 7 years ago

I'd like to bring up a secondary goal here: We desperately need something that can overshadow HaskellWiki. That site dominates Google search results and presents a truly awful face of the ecosystem.

snoyberg commented 7 years ago

@JeremyBellows It looks like the biggest thing we'll need on this is someone to coordinate the effort. You're seemingly getting support from everyone involved (myself included), want to step up to the plate? I'd be happy to assist on the implementation side.

vbop9834 commented 7 years ago

Sure! I'll work on a general outline for the GHC user manual, submit it to this thread, get some feedback, and iterate. Once we have a general outline that we agree encapsulates the GHC user manual then we can begin in the implementation phase which will be clear once the outline is done.

vbop9834 commented 7 years ago

May I have access to the google analytics for the haskell-lang.org site? This would help with figuring out what the current user patterns are for the haskell-lang.org site content which might reveal some content we can utilize for abstracting the GHC user manual content.

snoyberg commented 7 years ago

Sure, can you send me your Google account address?

vbop9834 commented 7 years ago

Pm over twitter?

snoyberg commented 7 years ago

That works for me.

vbop9834 commented 7 years ago

Here's a starter outline. Feedback is encouraged! It's best to start simple so phases 2-4 are generalized for the potential lessons we'll encounter.

Phase 1

Goals

Tasks for Phase 1

Resources

GHC User Manual - https://downloads.haskell.org/~ghc/8.0.2/docs/html/users_guide/index.html

Tasks

Phase 2

Goals

Phase 3

Goals

Phase 4

Goals

Phase 3 and Phase 4 Notes

There will need to be some scale to determine what GHC user manual sections will be selected for phase 3. A data driven approach is the best but that would require data collection and access to the GHC user manual. We could host a popular vote on some medium to gather a small pool of opinions on which content would be most useful. Ideas?