Create documentation for projects-check page

[blulady]

Dependency

• Add a Tools filter to the projects check page #4427
• Updating Wiki: Move Current Wiki to New Repository #3636
• ER: Project's Check page not working #5677

Overview

We need to document for the dev and product teams how the https://www.hackforla.org/projects-check page works

Details

• This issue was created in response to this issue Create a copy of the project page with only two filters: technology and language #2502, and the pr made it possible Projects page copy with only technology and language filters #3452

Action Items

• Create documentation on the projects-check hidden page for the Wiki. That page will contain:

  • Info about all files used to build the page

  • How the page should be used internally by product teams and others, for example:

    • Product team is going to add it to their monthly actives to check each this page to see if any of the language or technologies are not properly assigned and then reach out to projects
    • This should be added as an example in the Wiki:

    E.g., currently 12 projects are using 'Dockerfile', but only 6 have 'Docker' listed under technologies. One of the projects has 'Docker' listed in technologies but because they don't have a 'Dockerfile', it does not show up on the 'Dockerfile' results:
    https://www.hackforla.org/projects-check/?languages=Dockerfile
    https://www.hackforla.org/projects-check/?technologies=Docker
    

  • Screenshots showing the page being used

• The Wiki is still in the process of being updated, therefore see How to Contribute to the Wiki and "Creating a new wiki page"
• Add link to the instructions created to this issue: Review project data to determine reclassifying requirements for their Technologies and Tools. #4262

Resources/Instructions

• https://www.hackforla.org/projects-check/
• Create a copy of the project page with only two filters: technology and language #2502
• Projects page copy with only technology and language filters #3452
• This issue is part of an epic: Epic: Make sure that the data in the project's page filters content is properly categorized #4434

[ExperimentsInHonesty]

• Product team is going to add it to their monthly actives to check each this page to see if any of the language or technologies are not properly assigned and then reach out to projects

• Add the following example to the wiki file on how to use the project's-check page

E.g., currently 12 projects are using dockerfile, but only 6 have docker listed under technologies.  One of the projects has docker listed on technologies but because they don't have a docker file, it does not show up on the docker file results
https://www.hackforla.org/projects-check/?languages=Dockerfile
https://www.hackforla.org/projects-check/?technologies=Docker

[HackforLABot]

Hi @mugdhchauhan, thank you for taking up this issue! Hfla appreciates you :)

Do let fellow developers know about your:-
i. Availability: (When are you available to work on the issue/answer questions other programmers might have about your issue?)
ii. ETA: (When do you expect this issue to be completed?)

You're awesome!

P.S. - You may not take up another issue until this issue gets merged (or closed). Thanks again :)

[mugdhchauhan]

Availability for this week:

• Daily @ 6 PM - 8 PM (GMT)

My estimated ETA for completing this issue:

• 6 Dec 2024 @ 8 PM (GMT)

[mugdhchauhan]

Projects-Check Page Wiki

Documentation for how the https://www.hackforla.org/projects-check page works.

The Projects-Check page is a hidden file accessible only through a permalink and is useful for the dev and product teams to ensure the project information is displayed correctly.

Files Information

Information about all the files that are used to build the Projects-Check page.

• _includes/current-projects.html - reusable HTML file for displaying the elements for filtering and searching for current projects.

• pages/projects-check.html - hidden HTML page for Projects-Check intended for internal testing which uses Jekyll to display current-projects.html. Jekyll variables, Google Tag Manager, and a header container with some information about our projects accompanied by an image are also used in this file.

• assets/js/current-projects.js - this handles the functionalities for filtering the projects. Based on the pathname the appropriate filter title will be displayed. For example, the 'Technologies' title will be shown for only the /projects-check/ page but 'Languages / Technologies / Tools' will be shown for the /projects/ page. The filter items should be the same for both pages but in the /projects-check/ page they are separated by individual categories.

Instructions

Instructions for using the Projects-Check page.

Using the page

Filtering projects

The projects that will be displayed on the page can be filtered in the following ways:

• By technologies
• By languages
• By tools
• Searching by keywords

Filtering by technologies, languages and tools can be achieved by selecting one or more filter items from their respective categories.

To search by keyword simply type into the searchbox and click the magnifying glass button to the right or press enter on the keyboard. To clear the contents of the searchbox you can click on the 'X' button adjacent to the magnifying glass button.

Removing filters

Filters can be removed in the following ways:

• By unchecking the checkbox of the filter items in any of the categories (such as Technologies, Languages and Tools).
• Pressing on the 'X' of the filter tag in the 'Applied Filters' section to remove that individual filter.
• Pressing 'Clear All' in the 'Applied Filters' section to remove all filters.

Viewing projects

To view more information about the project you can click on the the available links on the displayed project card.

The project's title may also be a link and clicking on it will provide additional information about the project such as Project Overview, Value, Resources, Current Project Team, and All-Time Contributors.

The available links may vary depending on the project. Examples of links shown on the project card include links to the project's GitHub, Slack, Wiki and Readme.

Example

An example of how the Projects-Check page should be used internally by product teams and others:

Product team is going to add it to their monthly activities to check each project in this page to see if any of the languages or technologies are not properly assigned and then reach out to projects.

E.g., currently 12 projects are using 'Dockerfile', but only 6 have 'Docker' listed under technologies. One of the projects has 'Docker' listed in technologies but because they don't have a 'Dockerfile', it does not show up on the 'Dockerfile' results:
https://www.hackforla.org/projects-check/?languages=Dockerfile
https://www.hackforla.org/projects-check/?technologies=Docker

Screenshots

• Filtering by technologies:

In the screenshot above, from the 'Technologies' category 'Docker' is selected and 6 results are displayed on the page (the first two projects can be seen in the screenshot). The results are sorted alphabetically and by status. The number of filters selected are displayed in brackets next to the category title. Also, the tag of the selected filter can be seen in the 'Applied Filters' section.

• Filtering by languages:

Similarly, in the screenshot above 'Dockerfile' is selected from the 'Languages' category and the relevant results and tag are displayed.

• Filtering by tools:

Similarly, in the screenshot above 'Calendly' is selected from the 'Tools' category and the relevant results and tag are displayed.

• Broaden displayed results (with multiple languages filters):

Screenshot above shows that selecting multiple languages broadens the filtered results. There is only one project that uses 'Dart' but there are more than one projects displayed because 'HTML' is also selected.

• Narrow displayed results:

Screenshot above shows that a filter from the 'Technologies' category with multiple languages narrows the filtered results. The languages filters are the same in the previous screenshot but now with 'Django' selected in the 'Technologies' category only two results are displayed.

• Removing an applied filter individually:

Animated GIF above shows that clicking on the 'X' of the filter tag in the 'Applied Filters' section removes that individual filter.

• Removing an applied filter by unchecking the filter item:

Animated GIF above shows that unchecking the checkbox of the filter item removes that filter.

• Clear all applied filters:

Animated GIF above showing that clicking 'Clear All' in the 'Applied Filters' section removes all selected filters and tags and the displayed results are updated.

• Searching by keyword:

Screenshot above shows that searching for 'Guide' displays results which include that word and also the tag is added to the 'Applied Filters' section.

• Error Message:

Screenshot above shows the error message that is displayed when there are a no projects that contain the applied filters.

[mugdhchauhan]

Notes for Projects-Check Page Wiki

I have added these notes to explain my choices, record my observations, and ask questions if any changes are needed to be made to the documentation.

@t-will-gillis Please could you let me know if the documentation (previous comment) is ok or if there any changes to be made?

Files information

Based on this PR #3452, the files used to build the Projects-Check page are:

• _includes/current-projects-check.html
• pages/projects-check.html
• /assets/js/current-projects-check.js

However, current-projects-check.js is now non-existent. Hence, why I have not included it in the documentation. I believe it is now handled by assets/js/current-projects.js.

Also, it may be possible to remove lines 21 - 23 from _includes/current-projects-check.html as there is no such JavaScript file:

<script src="/assets/js/current-projects-check.js">

</script>

Upon looking further, the entire _includes/current-projects-check.html file is not currently used for the Projects-Check page as on line 23 of the pages/projects-check.html the file that is referenced is current-projects.html:

{%- include current-projects.html -%}

Therefore, I have listed _includes/current-projects.html as one of the files used to build the Projects-Check page in the documentation (instead of _includes/current-projects-check.html).

The information that I have provided for assets/js/current-projects.js in the documentation relates specifically to the Projects-Check page as this JavaScript file is large and contains features that are common to both the /projects-check/ page and the /projects/ page.

I have not included .scss files and each of the individual project pages in the list of the files that are used to build the Projects-Check page as they are referenced in other files.

Instructions

Example subheading - I have used the text from the issue summary to complete this section.

I have modified slightly "monthly actives to check each this page' to "monthly activities to check each project in this page".

For the example to be added to the wiki "E.g., currently 12 projects are using 'Dockerfile' ..." I have noticed that there are actually currently 11 files that are using 'Dockerfile' but since this is only an example I have not changed it.

I also believe that I do not have to check each project's listed languages and technologies as that is not required for this task and it is the action of the Product team. So, only the given example is used in this section.

The issue summary says that the documentation should contain how the page will be used by the "product teams and others." As I have used the example provided I believe it covers the product teams and others.

Screenshots

In the filtering by language screenshot we can see that '(1)' is displayed next to the 'Technologies' category although no technologies are selected. The number of filters selected should be displayed next to the relevant category. In this case, the '(1)' is expected to be displayed next to the 'Language' category as only one filter 'Dockerfile' is selected. The same issue can be seen in the filtering by tools screenshot. This could be fixed. I also looked at the projects page (https://www.hackforla.org/projects/) and it is displaying correctly on that page for all of the filter categories.

Previously in PR #3452 only two filters were used. Currently, there are three filters (Technologies, Languages and Tools). A search feature and filter tags are also added. I have added screenshots for these in the documentation as well.

[mugdhchauhan]

Progress Report

Progress: "What is the current status of your project? What have you completed and what is left to do?"

• Created documentation for the Projects-Check page that contains information about the files used to build the page, how the page should be used internally by the product teams and others, screenshots of the the page being used.
• Added the link in the table on the How to Contribute to the Wiki page
• Added the link to the issue Review project data to determine reclassifying requirements for their Technologies and Tools. #4262

Blockers: "Difficulties or errors encountered."

• No Blockers. I believe I have completed the tasks as per the the issue summary. I am happy to make changes if needed.

Availability: "How much time will you have this week to work on this issue?"

• Daily @ 6 PM - 8 PM (GMT)

ETA: "When do you expect this issue to be completed?"

• Completed the documentation and added the links where needed.

Pictures (optional): "Add any pictures of the visual changes made to the site so far."

• No visual changes to the site.

[mugdhchauhan]

As I had a question about this issue and put the label "Status: Help Wanted", I will wait for @t-will-gillis response before possibly adding the label "ready for dev lead".

[t-will-gillis]

Hey @mugdhchauhan Fantastic job! Great work explaining the process-the descriptions are very thorough including all of the gifs. You also have linked this to the "How to Contribute to the Wiki"

Thank you for your outstanding work!

Closing this as successfully completed