apache.org should use tag-based navigation

[bdelacretaz]

With more than 200 pages and a suboptimal organization, it's often hard to find pages on the apache.org website.

I think adding tag-based navigation, like we have on the Sling website (see https://sling.apache.org/tags/community.html for example) would help a lot, and gradually tagging pages would help find duplicates and redundancies.

I know little about Pelican, I tried adding tags with the below patch but that didn't work, I suspect that the custom GFM Markdown parser that's used doesn't support lists of tags in page metadata (front matter).

Maybe someone who's better at Python than myself can find out more details and improve that parser if my assumption is correct?

See the below example for what doesn't work.

Patch that adds tags and doesn't work.

We'd need more than that of course, but it looks like Pelican takes care of tag-based navigation out of the box. Adding tags in a similar way to the pelican-quickstart example site articles does provide tag-based navigation with the default theme.

With the below patch, the tags are output as

<h1>TESTING TAGS</h1>
    <p>p</p>
    <p>m</p>
    <p>c</p>
    <p>,</p>
    <p> </p>
    <p>p</p>
    <p>o</p>
    <p>l</p>
    <p>i</p>
    <p>c</p>
    <p>y</p>

with each character considered a separate element in the list, instead of the expected <p>pmc</p><p>policy</p>

Here's the patch that I tried:

diff --git a/content/dev/pmc.md b/content/dev/pmc.md
index 1f6eb4a4c..909681f87 100644
--- a/content/dev/pmc.md
+++ b/content/dev/pmc.md
@@ -1,7 +1,8 @@
 Title: Project Management Committee Guide
 license: https://www.apache.org/licenses/LICENSE-2.0
+Tags: pmc, policy
 
-# Project Management Committee Guide
+# Project Management Committee Guide #3
 
 This guide outlines the general responsibilities 
 of [Project Management Committee](/foundation/how-it-works.html#pmc) (PMC) members in managing their projects and common how-to procedures for 
diff --git a/theme/apache/templates/base.html b/theme/apache/templates/base.html
index 87f3cf2bc..3e1a61f07 100644
--- a/theme/apache/templates/base.html
+++ b/theme/apache/templates/base.html
@@ -41,6 +41,12 @@
 
 <body{% if page.bodytag %} {{ page.bodytag }}{% endif %} >
   <!-- Navigation -->
+  <h1>TESTING TAGS</h1>
+    {% for tag in page.tags %}    
+    <p>{{ tag }}</p>
+    {% endfor %}
+    
+    
   <header>
        <div id="skiptocontent">

[Humbedooh]

the tags in the example are treated as a string, not a list. so when you iterate, you get one character at a time.
You may want to do something like:

  {% if page.tags %}
    {% for tag in page.tags.split(",") %}
      <p>{{ tag.strip() }}</p>
    {% endfor %}
  {% endif %}

[bdelacretaz]

Makes sense, thank you, and I think this splitting can later by done in the gfm.py plugin so that Pelican gets a proper list of tags.

Howewer, enabling the Pelican TAGS_SAVE_AS option for tag-based navigation doesn't currently work in the infrastructure-pelican module, I've created a separate issue for that, apache/infrastructure-pelican#49

[bproffitt]

Just to let you know, while I am very intrigued by the idea of this kind of navigation, I want to put a pin in it for now. The M&P team is currently working on addressing the navigation issues (and other content-related issues), and we would like to get those done before implementing a change like this.

[bdelacretaz]

Ok, noted. I might start adding tag-based navigation to https://community.apache.org/ which is built on Hugo which I know better, if I do that I'll mention it here for review.

[bdelacretaz]

I have now added tag-based navigation to the community.a.o website, I think the following is a convincing scenario where tags help someone find relevant related content, once they have found an initial page:

• User finds https://community.apache.org/pmc/new-member.html by searching or receiving a link
• User sees the small tags at the top of the page, "pmc", "election" which hint at related content
• User clicks the "pmc" tag link which leads to https://community.apache.org/tags/pmc.html , exposing related pages

IMHO, menu-based navigation only goes so far as it's always designed for a single mental model that might not be the user's model. Tag-based navigation provides a different angle on the content that's quite useful, especially when content is not organized as well as it should.

Note that only a subset of that website's pages have been tagged for now, you won't find everything via tags.

[bdelacretaz]

A recent discussion on members@ makes me think that it would be useful to add a policy tag to pages that contain ASF policy information, as opposed to just being informative. That content must be handled with special care and changes might require Board approval in some cases.

Even if such a tag is not used right now in the website publication, I think having it in the content can help.

I think a good number of the pages linked from https://www.apache.org/dev/ fall into this "policy" category, as well as a lot of what's under https://www.apache.org/legal/ and https://www.apache.org/foundation/marks/

[sebbASF]

Would it be worth creating a policy branch where people can start adding policy tags?
This would not interfere with the rebuild, but would be a way of recording which pages need the tag later.
Just a thought.

[bdelacretaz]

I'm +1 on adding policy tags in a branch, or even in main as far as I'm concerned as those are unobtrusive, not being used at this point. But let's see what @bproffitt thinks!

[sebbASF]

I deliberately did not suggest the main branch as that might affect the redesign work.

I would be very surprised if there was any objection to creating a branch.

[sebbASF]

I have done some further experimenting with www-site.
AFAICT, tags defined in pages are not added to the general tag pool, so the tags variable provided to the templates is empty.

It looks like tags are only collected for articles, at least by default.
As such, I'm not sure they would be much use.

Further, tags on pages are treated as strings (which is why split() is needed), whereas article tags are automatically split on semi-colon (if present), failing that comma.

[sebbASF]

It does not seem possible to use the standard tag processing code, as that only works for articles.

However, it is possible to intercept the page_generator_finalized signal, at which point all the pages have been processed. It is then a matter of scanning all the pages, accumulating the pages for each tag.

There is no built in way to process these.
However can create a new page for each tag, passing in the pages for that tag.
Likewise create a tag index page containing all the tag names.
Since these pages have different processing requirements, they must be associated with templates created specifically for the purpose.

Note: the gfm plugin behaves differently from the pelican markdown plugin; it returns page tags as a string, whereas the default plugin creates a list of Tag entries. This is easy enough to work round.

[sebbASF]

I have created a sample tag plugin in the preview/tags branch.

The summary index is at https://www-tags.staged.apache.org/pagetags; this links to the individual pages for each tag.

Note that the tags are just samples, and there are not very many of them.

There will need to be a link to the pagetags.html page; perhaps next to the search button?

I did not add tag indicators to individual pages; I'm not sure how useful that would be.

Also it will be messy to do unless apache/infrastructure-pelican#75 is implemented

[sebbASF]

@bdelacretaz:
Now that the site rework has been completed, perhaps it's time to start tagging pages.

Feel free to update the preview/tags branch with additional tags (or indeed change the sample ones I added).

Please don't make any other changes to the content pages, as that could make it harder to merge the tags into the main site.

[bproffitt]

@bdelacretaz Please hold off on this, I have not decided if we are using tagged-based navigation yet.

[loganloganlogan]

Hi @bdelacretaz, I completely agree that the site needs better discoverability. Having pored over sitemap data to update the navigation, here's my perspective. The TL;DR is that implementing better categorization (rather than tags) would improve discoverability in addition to improving new contributor onboarding (which tags would do a poor job of).

The Sling website uses categorization well and is more akin to docs. When looking at Sling’s analytics, one doesn't see visitors using tags to find content; rather they appear to navigate directly to the pages they are looking for because the site implements categorization well.

The downside of tags is that they are unstructured and unlimited, which means that if we don’t define a set of tags at the beginning - we could quickly see “tag sprawl” that begins to make tags meaningless. (You see this a lot on blog tags - it can start to have the opposite effect of what was intended - by adding too many tags for every page.)

The other downside is that tags aren’t helpful for people new to ASF. How do they know where to start? Tags are non-linear nor progressive. For example, there are currently 20 obvious pages in the sitemap that could be tagged with “trademark" (and probably many more). If a newbie saw a list of 20+ pages, they’re less likely to know where to start. On the other hand, categorization creates a more linear path with pages visible in the recommended order. They provide a more structured approach that provides flexibility as ASF continues to grow and adapt.

To resolve the issue of dense content, my suggestion is to create a more docs-like site for the ASF. This requires a centralized effort to understand the content, categorize it, and develop an appropriate IA. It’s categorization that the ASF site sorely lacks today that we could only partially solve with the new website top-level navigation.

I'd love to hear your thoughts.

[bproffitt]

Okay, with no further discussion, closing.

[bdelacretaz]

Sorry that I didn't reply earlier. I understand your reasons for not adding tags at this point, but I also think the website redesign has made some pages harder to find from the navigation. It seems to be targeted to non-ASF audiences which is great, but we also have a lot of internal information, under /dev and /legal for example, that our PMC members must be able to find, for reference.

However, given the size of the website, creating a navigation that works for all cases is probably hopeless, so the focus (IIUC) on external audiences makes sense.

Covering those parts which are not easily reachable by navigation is where I think tags might help, if I'm looking for PMC reporting guidelines for examples, looking for pmc + report tags would feel natural, and tags are also a great to way find similar pages on multiple axes. But I agree that defining a meaningful taxonomy is a challenge.

One major thing that changed since I opened this ticket is that the website search works very well now, so for this example, searching for "pmc report" does bring me to the right page fairly easily.

So I guess we need to emphasize that and make sure the search continues to work well, and if people still have problems finding things I'd come back with the tags suggestion.

[bdelacretaz]

my suggestion is to create a more docs-like site for the ASF...

Do you mean moving the current internal-facing content to a different website? I think that would be great, as long as redirects from existing "important" URLs are added.