Section title in article title?

[systimotic]

In https://github.com/freeCodeCamp/guides/issues/477, the inconsistency of the naming of articles in the Javascript section was pointed out. Now, Javascript has been removed from nearly all titles in the folder.

On Gitter, @davcri pointed out something similar in the Java section. Here's a screenshot of what it currently looks like: Not great. He submitted a PR to fix this: https://github.com/freeCodeCamp/guides/pull/631 A similar inconsistency is also very visible in the CSS section. In contrast, the Agile section only has the word "agile" in two of the titles.

I personally feel like the article titles without the section titles in them are a lot easier to read in the navigation. However, @davcri also pointed out that the README implicitly suggests you should put it in the title: https://github.com/freeCodeCamp/guides#article-title

There's a tradeoff here. In search results, having the full title is easier. In our own searchresults, this could be replaced by the breadcrumb (https://github.com/freeCodeCamp/guides/issues/206), but I imagine having more things in the title would still be good for SEO. From a UX point of view, not having all that extra text in the nav is definitely easier.

@Bouncey @HKuz @erictleung @texas2010 What do you think? (we need an @freeCodeCamp/guide 😄)

[erictleung]

@systimotic I agree there appears to be some redundancy. I'm not sure if adding the title there adds or removes anything from SEO? Maybe @Bouncey can speak more on this. I agree on @systimotic's points on the tradeoff paragraph.

Question: does searching for things make it more difficult without the language name in it?

Side note: to make searching more efficient, should maybe have a tags attribute within the YAML to use within search? Would this even help?

[johnkennedy9147]

It would be useful to have the language indicated in the search results, but in a consistent place. Is it possible to include the top level navigation folder. By which I mean just the name X from the folder: guides/src/pages/X/{subsection...}/article.

So for example:

would become

[systimotic]

@johnkennedy9147 I agree 100%, that's what I suggested in #206 too.

[davcri]

I personally feel like the article titles without the section titles in them are a lot easier to read in the navigation.

I also think that it would be better: it is more elegant. Simplicity is a core value of FCC Guides and this should be reflected also in the UI/UX (as far as it doesn't affect SEO).

PS: :+1: for a gitter freeCodeCamp/guide :smile:

[davcri]

@johnkennedy9147 I like the idea: search results can be improved. I really like the solution used by devdocs.io:

So ideally:

[johnkennedy9147]

@davcri Ooh - thats pretty, never seen that site before, 🔖 now

[HKuz]

I really like how DevDocs handles the search results - either an icon or the word (as @johnkennedy9147 's example uses) would be an elegant solution.

I can give some backstory for the README. When the Guide was coming together this summer, we were looking at the top search results for popular queries (like if I searched 'HTML lists', what came up), and modeled our example titles off those results. But with more discussion since then, we have changed tack on a few things (we got rid of the 'article' in the URL, for example, to simplify it).

As for SEO, pretty much what I know is in the README (use short, concise titles, first paragraph is a simple explanation ~<160 chars). @QuincyLarson - I know you did a lot of research on it this summer, if you have a moment, would you mind weighing in on that for article titles?

[QuincyLarson]

@davcri Yes - I am a huge fan of DevDocs and I've asked its creator for advice on the Guide in the past. If we can find a nice svg image, we could use that alongside the heading - just like on DevDocs.

We could then use this in search as well as in the side navigation. That said, we should continue to use the breadcrumbs on the articles and in the search results, as they are unambiguous. I noticed that even Google results now use breadcrumbs on search results:

@HKuz Yes - I still like that approach. That is similar to how Wikipedia does it - a short summary up-top and and then a longer explanation broken into sections. One issue with Wikipedia is the summaries up top can get pretty long (like on their article on functional programming). That is a trap we should avoid falling into.

Even though we've built out sophisticated search on the Guide, I still imagine the main way people are going to get access to this is through Google search - just like they do with other reference tools like Wikipedia, Stack Overflow, and the MDN. So we still want to be mindful of the SEO impact of our decisions. I think front-loading a summary in our articles - to the extent possible - is a good approach from an SEO perspective.

[davcri]

What about keeping the HTML title with the <language> <article> structure but removing it from the article's header ?
Example:

---
title: Java Access Modifiers
---

# Access Modifiers

The HTML title should work well for SEO and, at the same time, we can remove some clutter from the sidebar.

[QuincyLarson]

@davcri yes - that's a good idea. We don't want clutter in the sidebar. Can you figure out a way to add the parent categories dynamically to each page's meta information?

[davcri]

With "dynamically" do you mean something like the following example ?

---

• index.md:

  ---
  title: Access Modifiers
  ---

• generated HTML page:

  
  <title>Java Access Modifiers</title> 

[QuincyLarson]

@davcri Yes - like that, where it's dynamically pulling in the parent categories and article title, so that it doesn't need to be hard-coded on every page. It should be part of the meta data and the title.

We have a breadcrumb at the top of the view, so it should be clear that "Docs Access Modifiers" are related to Java. We just need to make the metadata correct for search engines and their web crawlers.

[davcri]

@QuincyLarson got it, thanks for clarifying! Unfortunately I don't know React and I can't implement it in short times, but with the help of other campers I think that it will be totally doable 😄 Maybe we can open another issue to discuss this.

About the main issue: I think that we all agree about using a title that doesn't repeat any string contained in the parent folder. If this is the situation we can:

• Unlock https://github.com/freeCodeCamp/guides/pull/631 and https://github.com/freeCodeCamp/guides/issues/477
• Update the README.md

[davcri]

I created a PR where we can discuss how to improve the README: https://github.com/freeCodeCamp/guides/pull/2276

[QuincyLarson]

@davcri OK - I've merged your PR.

Google still isn't picking up the hierarchy of the files, so we still need to update the meta information. Is anyone interested in helping with this?