Finding relevant documentation via search engines is incredibly difficult about haskell-lang

[vbop9834]

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.

[Blaisorblade]

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]

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]

@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

• Create an outline of the GHC documentation
  What are the main sections of the GHC documentation? How could we reorganize that information to be simpler to consume for our target audience?
  Target audience at first should be newcomers looking to learn more. This should allow for a thought environment that will foster the principle of occam's razor
• Write brief descriptions of the GHC documentation sections
• Place a ton of links to the GHC user manual

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]

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:

• manual is not searchable (a custom Google search or migrating to readthedocs might be options?);
• 404s on the manual could be redirected to "close" pages to improve SEO (not 100% sure why it matters);
• that's hard because manual pages are huge and most links are to sections (not 100% sure why it matters).
  Maybe @chris-martin wants to pitch in ideas?

[vbop9834]

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]

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]

@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]

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]

Sure, can you send me your Google account address?

[vbop9834]

Pm over twitter?

[snoyberg]

That works for me.

[vbop9834]

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

• Identify associations in targeted site content with the GHC user manual. Targets are determined by user flow data in site analytics.

Narrowing the Focus

Looking back at the last 4 months of data, the following pages should be targeted

• /get-started
• home
• /library/http-client
• /news
• /documentation

Tasks for Phase 1

Resources

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

Tasks

• Identify /get-started content that corresponds with the GHC user manual
• Identify home content that corresponds with the GHC user manual
• Identify /library/http-client content that corresponds with the GHC user manual
• Identify /news content that corresponds with the GHC user manual
• Identify /documentation content that corresponds with the GHC user manual

Phase 2

Goals

• Create a tutorials page to capitalize on common user flow data landing on a tutorials page where available
• Identify associations in tutorials that can be linked to the GHC user manual

Phase 3

Goals

• Select simple GHC user manual content and find associations between current site content. If none exist then carry over to phase 4

Phase 4

Goals

• Create site content for summarizing sections carried over from Phase 3

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?