search

HTTPArchive / almanac.httparchive.org

HTTP Archive's annual "State of the Web" report made by the web community
https://almanac.httparchive.org
Apache License 2.0
622 stars 182 forks source link

Review the interlinking of the chapters #253

Closed tunetheweb closed 5 years ago

tunetheweb commented 5 years ago

I think we should do a review of all the chapters after they are completed and ensure they are interlinked as much as possible. There is a lot of overlap in the chapters and one of the great things about the web is it is built on links! I think doing this would make the whole project feel more like a cohesive resource rather than as separate, almost unrelated, chapters.

Taking the SEO chapter as an example (and not trying to pick on those that worked on that chapter, but it's a good example to illustrate what I'm talking about!) it mentions markup (without a link to that chapter), accessibility (with a link to that chapter), speed/performance (without a link to that chapter), security (without a link to that chapter). Should we do more to link those other chapters where it makes sense? I'm not saying force in links when it's unnatural just for the sake of it, but I think there are a lot of cases where this would make perfect sense and it's almost weird not to have them linked.

I think this should also be part of the copyediting issue but suspect another quick check after - even if only to check the links actually work as in many places (e.g. the SEO chapter mentioned above, or even my own HTTP/2 chapter) they are place holder links for now - hence why raising this as a separate issue.

Let me know your thoughts and feel free to close this issue if you disagree or think it's already covered.

Happy to own this one if no one else wants to - though I am away this weekend and that's getting close to the proposed launch date so maybe someone else can help out too.

AymenLoukil commented 5 years ago

+1000

AymenLoukil commented 5 years ago

I can help, as a first step, drafting the logic of interlinking. (link when cited + suggest 2 or 3 chapters to discover below the content..)

tunetheweb commented 5 years ago

suggest 2 or 3 chapters to discover below the content

Oh I like that!! Would have an impact on the design though so may not have time.

rviscomi commented 5 years ago

Strong +1 to better interlinking.

The way to link to another chapter in the markdown is [text](../chapter-slug) where the chapter slug is a lowercase and sanitized version of the chapter title according to this rule:

https://github.com/HTTPArchive/almanac.httparchive.org/blob/11de06a5a19679d751cbec168c5c8a63099f9780/src/main.py#L36-L38

The canonical URL of a chapter will look like https://almanac.httparchive.org/en/2019/markup, so by using a relative URL (../) we'll retain the user's language selection (eg en).

Note that the linking won't work when previewing the markdown on GitHub, only when viewing it on the website locally or in production.

I also like @AymenLoukil's idea to suggest related chapters but agree with @bazzadp that we should avoid adding any new components to the design this late.

rviscomi commented 5 years ago

I've added a note to #218 for editors to keep interlinking in mind. We can use that issue to track the progress of this task. Closing this one for deduping.