Content classification

Is this about an existing page or a request for a new one?

Request for a new page, category, or section.
The title of the new content is: "Business strategies for Open Source"
If a page, it will belong to this category: New category, or FOSS

Content description

A common question we receive is how to be sustainable with Open Source. There are various resources around the web for this but aggregation would help to make them more discoverable.

Summary

Travis CI has changed their offering to open source projects. And the suggested platform travis-ci.org is not longer available:

• https://blog.travis-ci.com/2018-05-02-open-source-projects-on-travis-ci-com-with-github-apps
• https://mailchi.mp/3d439eeb1098/travis-ciorg-is-moving-to-travis-cicom

I have experienced long wait times on travis-ci.org (before the merge), and it seems that the free tier is quite limited. Other projects have moved away from this platform.

What you expected to happen

My suggestion is to remove TravisCI from the list of suggested CI platforms.

Summary

Migrate the Data Ethics & Transparency category in the Open Source Inventory into the Data Science & AI Toolkit.

Background

@dalvarez83 is leading as our Data Science & AI Mentor at the Venture Fund, where we are also leading on creating new toolkits to support Venture Fund open source start-ups. The Data Ethics & Transparency category on this site was always a unique topic on the Open Source Inventory and had great content originally written by @Nolski during his time at UNICEF. It makes a natural fit in the Data Science & AI Toolkit to be published along with other contextually-relevant data. So, let's move this content there.

Details

1. Copy content/data/ from unicef/inventory and add it as content/privacy-ethics to unicef/ooi-toolkit-data
2. Rename category in _index.en to Data Privacy & Ethics
3. Submit a Pull Request to unicef/ooi-toolkit-data.

Note: We don't want to remove it from unicef/inventory yet. We want to redirect the URLs to the new location to preserve historical links. But this will require some improvisation for linking across different Hugo sites. We'll think through this challenge in a different issue.

Outcome

Data Ethics & Transparency content in Open Source Inventory is given better visibility as a building block of the Data Science & AI Toolkit.

Summary

When a doc writer uses an Automatic TOC in an AsciiDoc file, render a table-of-contents of the article.

Background

Is your feature request related to a problem? Please describe:

AsciiDoc has nice support for Automatic Table-of-Contents, but the theme does not support them.

Describe the solution you'd like:

There is room to be creative on appearance. But a table-of-contents should appear when the directive is used, and it should have support for nesting (or, indention levels) up to six sub-heading sizes.

Describe alternatives you've considered:

Table-of-contents are pretty straightforward; they are as old as books.

Details

There is room to be creative on styling and general appearance.

The tricky part is finding the right place in the unicef/inventory-hugo-theme where we can "catch" the :toc: directive and however it gets interpreted (or not) by Hugo at site build-time.

See this page to see an example where I am manually creating a table-of-contents by hand and updating links myself. Not ideal!

Outcome

When an author wishes, they can add a table-of-contents to a longer article to make it easier to navigate and click through.

Summary

Show breadcrumb navigation at the top of each article, connecting back to the site home page and the current categorey.

Background

Is your feature request related to a problem? Please describe:

It can get confusing to navigate in sections with a lot of content.

Describe the solution you'd like:

Breadcrumb navigation is ideal. It is not flashy, it is not anything new, but it is an old concept and some users and readers will expect them.

Describe alternatives you've considered:

There are lots of ways to fancy or glitter this up, but best to keep it simple. Breadcrumb navigation fits the bill, and gives a boost to search engine discoverability.

Details

Two styles of breadcrumb navigation will be used:

• For category landing pages (i.e. _index.en.md): Home > <b>{CATEGORY_NAME}</b>
• For articles/content: Home > {CATEGORY_NAME} > <b>{ARTICLE TITLE}</b>

The breadcrumb navigation should appear at the top of the document, as a "header" of sorts for each article.

This change needs to be made to unicef/inventory-hugo-theme.

Outcome

• Easier navigation throughout the site, especially as content grows
• Improved Search Engine Optimization (S.E.O.)

Summary

All sub-headings should have a one-click way to copy a link to your clipboard for a specific section of an article.

Background

Is your feature request related to a problem? Please describe:

Sometimes I want to link to a specific section of a longer article. I might not want to highlight a full article, but one specific part.

Describe the solution you'd like:

I like using something like the :link: emoji (🔗) on hover-over on sub-headings in an article. The 🔗 icon is usually intuitive about what it means.

Describe alternatives you've considered:

I expect my readers to scroll through the page for the one section of an article I mention while on a support/mentorship call. Not ideal at all!

Details

I like this example from the vrapeutic/vrapeutic.github.io site. This site is not Hugo, but I think it gets the idea across of what I am looking for!

Outcome

Easier to point someone to a specific section of an article, instead of asking them to search through a long article for the small part I mention in a conversation

Hi! I saw you added the page on ethics traps and just wanted to let you know that that information has been pulled from the below paper. I'm not sure why I didn't cite it on the librecorps page but just wanted to let you know :)

https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3265913

Summary

When a hyperlink is shared from this website on a social media application, it should pull OpenGraph image and article metadata into the preview box.

Background

Is your feature request related to a problem? Please describe:

When I share a link from the UNICEF O.S. Inventory site, the preview box only shows the article/page title. It is not engaging and not descriptive of the content on the page.

Describe the solution you'd like:

The social media "preview box" should show an OpenGraph image (e.g. site logo), a page title, the site title, and an article/page description if it exists.

Describe alternatives you've considered:

Do nothing. Does not mitigate user engagement concern, i.e. by better describing the page content, an interested reader is more likely to discover this content.

Details

Some metadata must be defined in the article/post front-matter:

• Article/post description
• Title (already required)
• Keywords

A image or logo could be optionally defined, but it should fall back on some kind of site-wide logo if a specific post does not define a custom image or logo.

Outcome

Better promotion and visibility into the content and knowledge published on this site, before clicking the link to figure out what is hosted in UNICEF O.S. Inventory

Content classification

Request for a new page, category, or section.
The title of the new content is: "Project Governance, Phase 1"
If a page, it will belong to this category: "Missions"

Content description

Often when I get close to graduation with a VF team, they are more mature and stable than the beginning of the investment period. We start to think about governance and how to leverage Open Source in a beneficial way for their business model (#37), but also how to manage expectations and trust in a community.

To that end, the Fedora Project is a good model of an established, mature community with solid values and foundations. Fedora has a vision statement (why do what they do), a mission statement (the impact of successfully meeting their vision), and a community statement (how they accomplish their vision and mission). There are other things that Fedora defines, but vision, mission, and community statements are good first steps for a newer project still finding its way in the Open Source world.

https://docs.fedoraproject.org/en-US/project/

Some guidance on what makes good vision/mission/community statements will help. This is also one that I could include peer review from some folks in industry, if they are willing to spare some time to take a look at a first draft.

Content classification

Is this about an existing page or a request for a new one?

Request for a new page, category, or section.
The title of the new content is: "On-boarding Guide for UNICEF Innovation Fund teams"
If a page, it will belong to this category: "Meta"

Content description

A single, absolute resource to use and distribute for UNICEF Innovation Fund teams when they join the Fund. The current workflow for on-boarding is spread out across multiple Google Drive and Sharepoint documents. Centralizing the Open Source-related content together here will provide a public, static resource to link in other communication guides.

Note that the #33 feature request would enhance this use case.

Summary

Fork the dot-hugo-documentation-theme repository to the UNICEF GitHub org so we can make custom changes and import them into our website.

Background

Is your feature request related to a problem? Please describe:

It is difficult to add custom changes or tweaks to the Hugo theme used for this site. We check out a git submodule of the upstream repository for the theme. This works, but it requires us to merge contributions upstream for them to be reflected in our downstream theme. We may add changes that are specific to the UNICEF use case for this documentation theme.

Describe the solution you'd like:

We need to fork the original theme to the UNICEF GitHub, set it up for contributions, and create some kind of documentation for how the theme works.

Describe alternatives you've considered:

We could send contributions upstream since they seem active, but I am worried the amount of energy we have for this task is too overwhelming for upstream. We also may want to experiment and try new ideas out, and it would be better to not send experimental patches to an upstream used by many people.

Details

Forking is the easy part, but here are things I also want to do:

1. Turn off issues, wiki, projects
2. Add a custom tab to this issue tracker instead for folks to open issues
3. Add a README to explain the project, link to the original upstream, and explain how changes are made
4. If possible, use the theme template as an example site (i.e. documentation about the theme itself while also demonstrating what the theme looks like and how it works)

Outcome

Easier for UNICEF team to try out new ideas, experiments, and design improvements to the theme for this site.

Summary

On following up Step 2 issue for Outreachy interns for this cohort, I got some challenges and difficulties. At the level of the cohorts.html, there was a problem at the level of line 110.

What you expected to happen

I actually expected this, as seen in the picture below.

That will be the correct output.

What actually happened

A description for this is the picture below.

Suggestion

I have a solution which will be appropriate for this error.

Summary

The navigation bar seems to be overlapping with the main content of all the cohort pages (https://unicef.github.io/inventory/cohorts/)

What you expected to happen

There is supposed to be some spacing between the navbar and main content like here for example.

Screenshots:

Summary

Use posts in a special category / archetype to appear at the top of every page when set to active

Background

Is your feature request related to a problem? Please describe:

Sometimes a maintainer needs to communicate information about the website and other news/updates. This is not instructional content, but informative content.

Describe the solution you'd like:

A group of AsciiDoc files can be created for each "alert" or news item. A news item can be set to active or inactive (Hugo draft?). Active news items appear in a carousel on each page. A news item may be dismissed by a user.

Describe alternatives you've considered:

Hard-code information into the theme. Easier, but messier. Decreases ability for others to re-use the Hugo theme.

Details

This needs some research and design work first before a coding solution. Wireframes or editing local HTML in the browser for a proof-of-concept is a good start. These can be uploaded as screenshots to this GitHub issue for review by maintainers.

Once the proof-of-concept is approved, we can explore how to do this with Hugo with the theme in follow-up discussion.

Some use cases for this feature are described below:

• Featuring newly-added pages or content on the home page
• Highlighting new Innovation Fund companies with a link to their profile (once #15 is implemented)

Outcome

Easier to communicate informative news to site visitors or updates about other UNICEF programmes and activities related to Open Source

Edit 1: Changed Markdown references to AsciiDoc. Added use cases discussed in stand-up with @Idadelveloper.

Content classification

Existing page.
The URL for the existing page is: N/A (addressing documentation source files, not HTML output)

Content description

When this knowledgebase first launched, Markdown was used. Later I discovered that Hugo can support AsciiDoc content, which I prefer because it has more advanced syntax features than Markdown and is more efficient to manage for collections of documentation (in my opinion 🙂).

Given most of the feature requests for the site theme are focused towards AsciiDoc content (#29, possibly #31 and #39), it makes sense to standardize on one and only one markup language. While multiple formats may be more inclusive, it adds a burden to maintenance and growing a team of reviewers who are comfortable working with both languages. I would prefer to create new content to teach AsciiDoc and help new writers instead of supporting two different formats.

This issue is a tracker for the remaining Markdown files in the Inventory:

• communities/_index.en.md
• data/_index.en.md
• design/_index.en.md
• dev-tools/_index.en.md
• dev-tools/continuous-integration.md
• documentation/_index.en.md
• faq/_index.en.md
• foss/_index.en.md
• foss/community.md
• foss/contributor-license-agreement-cla.en.md
• hardware/case-studies.md
• hardware/documentation.md
• hardware/licensing.md
• hardware/projects.md
• hardware/reading-list.md 534e3c8
• missions/_index.en.md
• missions/codes-of-conduct.en.md
• project-management/_index.en.md
• project-management/project-boards.en.md
• reproducibility/_index.en.md
• reproducibility/reading-list.md

Related: See jgm/pandoc#7435 which if implemented, would make this work easier.

Summary

Document how to clone this repository with the git submodule for inventory-hugo-theme

Standard debugging steps

How to reproduce?

$ git clone [email protected]:unicef/inventory.git
$ cd inventory/
$ hugo serve

Error: Error building site: "/home/idadel/Desktop/Unicef/inventory/content/faq/_index.en.md:6:1":
failed to extract shortcode: template for shortcode "faq" not found

Expected behavior

$ git clone --recurse-submodules [email protected]:unicef/inventory.git
$ cd inventory/
$ hugo serve

Start building sites … 

                   | EN  
-------------------+-----
  Pages            | 64  
  Paginator pages  |  0  
  Non-page files   |  0  
  Static files     | 17  
  Processed images |  0  
  Aliases          |  0  
  Sitemaps         |  1  
  Cleaned          |  0  

Built in 1077 ms

Other details

Need to address with obvious documentation in the README, because this is not an obvious step.

Content classification

Request for a new page, category, or section.
The title of the new content is: "Inventory maintainer's guide"
If a page, it will belong to this category: "Meta"

Content description

General overview of important considerations and checks for maintainers when working with this repository. Touching on governance pieces but not fully unpacking a whole governance structure on what is still, for now, mostly a one-person project.

What this guide or checklist should cover:

• Helpful Hugo documentation pages 60d97c2
• Issue label conventions 4cb87e7
• Commit message conventions 665ed2d
• AsciiDoc syntax cheat sheet b0bc3b1
• CI pipeline diagram
• How to update git submodule for theme as a maintainer 2a31b94
• How development decisions are prioritized 3ab71cb

This came up in conversation with BX Smart Labs in their monthly Open Source Mentorship check-in call on 6 January 2022.

Metadata

• Article/page title: Synchronous and asynchronous communication tools
• Category: Project Management
• Tags: communication, community

Content description

• Intended audience(s): Open source community leads, developers, project managers, and key collaborators in on-going collaboration with a project
• Why should this page exist?: To explain a key difference between virtual and online communication platforms, provide examples of each, and offer pros/cons for each type of comms tool.

Content description:

1. Intro to chat platforms for open source communities
2. What are synchronous communication tools? (pros/cons)
3. What are asynchronous communication tools? (pros/cons)
4. Picking a tool for your community
5. Case studies and examples

Content classification

Is this about an existing page or a request for a new one?

Request for a new page, category, or section.
The title of the new content is: "Project charters"
If a page, it will belong to this category: "Missions"

Content description

In the first quarter when we work with an Innovation Fund team, we focus on the "Foundations" phase of their workplans. Some of the activities that we focus on in the Foundations phase are listed below:

• Drafting a project vision and mission
• Creating a community statement and commitment
• Deciding on a licensing strategy
• Creating interfaces for public engagement in an open work (e.g. Codes of Conduct)
• Considering trademarks and branding assets

We can consolidate these interspersed activities into a single one. This fits into the purpose of the "Missions" category, which is intended to be self-guided tools and templates for creating different pieces of an Open Source project. Defining these tasks into a public project charter is important to set goals and expectations in reality from an earlier stage in the process.

Therefore, we can create project charter mission to guide someone through this. We will use this as a "homework" assignment for the incoming 2021 Blockchain cohort joining the Innovation Fund now.

Summary

Create onboarding guidance for future interns or volunteers who would work on the UNICEF Open Source Inventory and/or the UNICEF Inventory Hugo theme.

Background

In the past few months, the Open Source Inventory has come a long way! The Team Profiles feature debuted and several start-ups are already featured on the Open Source Inventory. Many other needed improvements were made, like breadcrumb navigation, compliance with UNICEF brand and identity requirements, adding a banner announcement feature, and several improvements to overall user experience. We also helped support the launch of another site using the same theme, the UNICEF Drones for Sustainable Development Goals Toolkit. Another site, the Sustain OSS Design & UX portal, is prototyping using the same theme.

Now that we are here and looking back on all that was accomplished these past few months, this is a good time to pause and reflect. We can look back on what worked well and what didn't. What things could be better documented or explained? What new features could use documentation? We can focus on the newcomer experience to make it easier for others who come after.

Details

The objective is to create onboarding guidance for new contributors or future interns. This could exist as a new page in the Meta -> Open Source Inventory category on the Inventory. The new contributor on-boarding guidance could cover topics like the following:

• Basic concepts about the project
• Learning about Hugo
• "Feature profiles" A.K.A. a detailed overview of a more complex feature of the Inventory theme and how it works
• Places to get help when stuck
• What the development workflow is like
• How to know what to work on? (Or, how does the GitHub project board work?)
• Tips and tricks for working on the Inventory theme
• Anything you wish you knew about earlier than you did

Pending review before end of sprint

Outside of the onboarding guide, this section is to keep track of any remaining issues or Pull Requests to close out with @Idadelveloper (also see this milestone tracker):

• PR Review: unicef/inventory-hugo-theme#39
• PR Review: unicef/inventory-hugo-theme#40
• Change under review: unicef/inventory-hugo-theme#45
• Bug fix: unicef/inventory-hugo-theme#36
• Change under review: #110

Outcome

A better experience for others who come after when working on the UNICEF Open Source Inventory and the UNICEF Inventory Hugo theme, and a kudos to @Idadelveloper's great work the past few months to improve the site. 🎉

Metadata

• Article/page title: Codes of Conduct
• Category: missions
• Tags: community

Content description

• Intended audience(s): Founders and/or community leads of Open communities
• Why should this page exist?: It does exist, but needs structural improvements and reorganization to map how it fits into existing Mentorship programme

Content description:

I developed a template for missions to follow a common structure and format, but the Codes of Conduct mission predates the template. It should be modernized to fit the new template.

Furthermore, there are some things that do not make sense to include. For example, Section 1, Quality of writing, is somewhat contradictory to Section 5, Use an existing Code of Conduct instead of writing one yourself. Section 1 applies more if you are writing your own Code of Conduct, but generally it is not a good idea to write your own unless you are very confident in that approach.

There are other parts that could be stripped or updated during a revision process to match the existing template.

Summary

When a code block attribute is used in an AsciiDoc or Markdown file, it should appear with the correct syntax highlighting if defined in the code block metadata.

Background

Is your improvement related to a problem? Please describe:

Sometimes code blocks are used in the site for different programming languages. They are always black and white, and sometimes difficult to read.

Describe the solution you'd like:

Syntax highlighting makes the code blocks easier to read, and uses common convention for what keywords and symbols to highlight with what colors.

Describe alternatives you've considered:

There are two possible implementations:

1. Leverage Hugo syntax highlighting with Chroma
2. Manually create CSS

Details

The best way to accomplish this is to use Hugo's syntax highlighting feature powered by Chroma. Hugo can parse a code block entity and return syntax-highlighted HTML. This is the cleanest way of implementing this without creating a ton of manual CSS rules and checks for several common programming languages.

No need to reinvent the wheel.

Outcome

Code blocks are easier to read and distinguish from other content in the UNICEF Open Source Inventory.

Summary

Wrap the text descriptions of the team profile cards around the logo to get rid of redundant space. When the number of characters of the short description increases, the spacing beneath the logo increases as well. It will be better if part of the text is wrapped around the image to give the cards a better look.

Screenshots:

Other details

This change should be made in https://github.com/unicef/inventory/blob/main/layouts/partials/cohorts.html

Summary

On following up Step 2 issue for Outreachy interns for this cohort, I got some challenges and difficulties. At the level of the cohorts.html, there was a problem at the level of line 110.

What you expected to happen

I actually expected this, as seen in the picture below.

That will be the correct output.

What actually happened

A description for this is the picture below.

Suggestion

I have a solution which will be appropriate for this error.

Summary

Add a one-click export option/button to export an article to a downloadable PDF document.

Background

Is your feature request related to a problem? Please describe:

Often with the Innovation Fund, we distribute multiple documents, agreements, and other resources at once when we bring in a new Innovation Fund start-up. Usually this is via Office 365 (Word) documents and PDFs. While it makes sense in this context to distribute files like .docx and .pdf, this method is also difficult to manage versioning and reliably maintaining a parent copy over time.

Describe the solution you'd like:

Some documents, which can be public, could be stored as editable source text in this repository. In the event where we create on-boarding packages tailored to a specific grantee, a one-click export of an article to a PDF enables parent copies to be maintained in GitHub, while also reliably fitting into this existing manual workflow.

Describe alternatives you've considered:

Not sure. This feature request requires more research on implementation before jumping in and writing code.

Details

The PDF export needs to be as simple as possible. The PDF metadata should also be derived from the document metadata defined in the article front matter. This needs research into the cleanest implementation possible. Ideally, it fits into the Hugo theme.

If it does not fit into the Hugo theme, we could explore some hacky ways of doing this in the Circle CI pipeline with pandoc, but that is a last-resort choice. It has messy design implications as a long-term feature, but addresses an immediate need.

Outcome

• New workflow: Better document versioning and easier to keep parent copies of important documents distributed on a recurring basis
• Old workflow: Distributing files at time of Innovation Fund on-boarding is still possible, fitting in with other documents we distribute unrelated to Open Source

Content classification

Is this about an existing page or a request for a new one?

Existing page.
The URL for the existing page is: https://unicef.github.io/inventory/faq/

Content description

In a recent workshop, several Office of Innovation portfolio managers and colleagues shared common questions and doubts they see about Open Source. In an effort to better answer common questions that come up across cohorts, the FAQ makes a better catch-all category for answers that might not belong to a larger content of section yet.

The questions from the workshop are listed below:

1. What are governance models for Open Source tech projects?
2. What license do we use?
3. How do you make money if you are Open Source?
4. How can you be financially sustainable with an Open Source business model?
5. Does this mean we will no longer be profitable?
6. How do you handle privacy if everything is Open Source? Is it less secure?
7. What is the benefit for them?
8. Miscellaneous questions about patents and patent law
9. How do you collaborate with other developers?
10. What are DevOps / infrastructure deployment best practices for Open Source software?
11. How do we decide what components should be Open Source?
12. "So we'll become a non-profit? Who will own our company?"
13. How do you safely and ethically create open data from an existing dataset?

Summary

Blockquote text renders in a way that I find difficult to read; it should be made prettier and clearly make an attribution.

Background

Is your improvement related to a problem? Please describe:

Blockquotes are not aesthetically pleasing to me. It only adds a gray background, and the blockquote citation appears outside the gray area.

Describe the solution you'd like:

The design cue to focus on is making it very clear that the text is a quote from an individual or third-party, and not from UNICEF. There are many experts who have contributed content to this site, and it is important to clearly attribute quotes and excerpts from others.

Describe alternatives you've considered:

Do nothing. Use the existing blockquote. This works, but… it triggers my OCD.

Details

There is some key information/aesthetics I would like to use:

1. Big quotes: The blockquote could begin with a big double-quote (") to cue the reader that they are reading a quote
2. Pictures/image: Adding a way to optionally display an image inside of a blockquote would be nice. In the above example, I'd like to include a small thumbnail of Bradley Kuhn next to the quote. But, I might not have a picture every time so it should work whether I have a picture or not.
3. Better attribution: The quote attribution sits outside of the gray background used for the quote now. It would be good to tie the attribution part of the UX into the rest of the blockquote.

Outcome

Blockquotes are aesthetically pleasing, match the look-and-feel of the site, and can be personalized with an image.

Metadata

• Article/page title: Overview of UNICEF Open Source Inventory
• Category: meta (or Mentoring after #136 is merged)
• Tags: TBD

Content description

• Intended audience(s): UNICEF Venture Fund mentors, portfolio managers, and start-up companies
• Why should this page exist?: Provide historical background and context about the site, share important information about maintenance, and deprecate the internal SharePoint doc with this content

Content description:

I have a document file with documentation that was used in an internal SharePoint drive about this site. However, the file was miscategorized and ended up being buried in the internal SharePoint. Since there is no confidential or sensitive data in this document, it should be made into a public page on this site. This will make it easier to discover and also keep like information together. I think it will also help to tell the "story" of how this site came to me and how it fits into the Venture Fund mentoring tools.

Summary

Callouts are a defined part of the asciidoctor tool in our pipeline, but the theme does not show callouts in the HTML page

Background

Is your feature request related to a problem? Please describe:

I want to use AsciiDoc callouts to annotate a blockquote or block of text.

Describe the solution you'd like:

The theme renders AsciiDoc callouts in the HTML page.

Describe alternatives you've considered:

You can manually do this without using callouts, but it is not standardized and sort order can change. It is easy for this to become messy and inaccurate in the long-term.

Details

This may require changes to our theme, or it may require engaging upstream Hugo community.

Option 1: Check support in the theme

We use the asciidoctor binary installed as a Ruby gem in our CI pipeline. What this means is, the asciidoctor tool should recognize AsciiDoc callouts, given the official AsciiDoctor docmumentation. There is a chance that Hugo also recognizes the output of asciidoctor but the theme does not implement the right CSS classes for it to render.

If this is the case, the theme needs changes to support AsciiDoc callouts so they appear as intended.

Option 2: Open an upstream issue

It is also possible that the hugo binary and its asciidocExt plugin don't know how to handle callouts.

If this is the case, we need to open a new issue upstream on https://github.com/gohugoio/hugo/issues/ to explore adding this functionality in a future Hugo release.

Outcome

A handy feature of AsciiDoc markup is available and rendered beautifully on the Inventory

Summary

Every article should have suggested reading content from elsewhere at the site. The suggested reading/articles should appear at the bottom of an article.

Background

Is your feature request related to a problem? Please describe:

Sometimes pages cover similar but different topics. It would be good to have a way to link out to related articles that might be interesting to a reader.

Describe the solution you'd like:

Best case scenario is using some kind of keyword indexing to determine which articles are related or not. For example, an article could take keywords in the front-matter definition. If keywords in one article match keywords from another, the article would appear at the bottom.

Describe alternatives you've considered:

Alternatively, we could manually specify specific articles in one article's front-matter. This is more manual and requires knowledge of other content in the site, but this would likely be a simpler implementation at the cost of more manual labor.

Details

Front-matter is the meta information at the top of every content. On this page, it looks like this:

---
title: "GPLv2 vs. GPLv3"
weight: 30

---

We could add support to our Hugo theme to look for front-matter tags like keywords, check for other content with the same keywords, and then show 3-5 articles at the bottom that match the keyword.

WordPress sites often have this functionality, and this feature request is partially inspired by seeing this in WordPress blog sites.

Outcome

Easier for readers to discover related content to what they are reading or searching for.

Summary

Use accessibility testing and/or linting tools to check for common mistakes on the Inventory site, and create new issues for identified bugs.

Background

Accessibility is a huge field, and it is naïve to think any website is 100% accessible. So, in order to better identify gaps in this website, we need to take an "inventory" of our own score on accessibility.

Details

Likely helpful to rely on some automated tools to help us figure these things out, but some of it could be manual evaluation and checking. One area I am particularly concerned about is color contrast for color-blind folks.

Outcome

Inventory dev team has a better picture of current accessibility concerns and issues with the current Open Source Inventory

Content classification

Is this about an existing page or a request for a new one?

Request for a new page, category, or section.
The title of the new content is: "Trademark strategies"
If a page, it will belong to this category: "Law & Policy"

Content description

The need for a clear trademark strategy is growing in awareness in FOSS. It is not a new need though, as shown by these existing examples:

• Fedora Project trademark guidelines
• The “Linux®” Trademark
• Python Software Foundation

Providing guidance, tips, and advice on how to approach trademark in a sustainable way as a business is helpful advice to standardize in the Open Source Mentorship programme. Providing advice on how to distinguish a product, add-ons and other extensions (both open and closed), and other components with Open Source I.P. meets a mentorship need for the Acceleration Funding cohort.

Consider examples like the following:

• Copyleft community:
  • WordPress plug-in development community
  • Bukkit/Spigot plug-in developer ecosystem
• Open core
  • GitLab

Another helpful pointer is GitHub's Minimum Viable Governance (MVG) document on trademark policy.

This Twitter poll available for a convenience sample on categorization.

Summary

It is unclear where to send improvements and fixes for the Hugo theme used in the Open Source Inventory.

Background

There is a complicated relationship between three repositories, for this one website!

• Upstream Theme: themefisher/dot-hugo-documentation-theme
• Downstream Theme: unicef/inventory-hugo-theme
• Hugo Website: unicef/inventory

The Downstream Theme is used as a git submodule in the Hugo Site. The Downstream Theme is a fork of the Upstream Theme. The Downstream Theme may contain UNICEF-specific changes that are not useful outside of a UNICEF context. This leaves an open question of how contributions to the site theme and style are to be made.

Details

I need to establish some contribution values or goals that can serve as a rallying point for the life of this project. Ideally, this belongs with the Contributing Guidelines, but it might be something to publish on the Hugo Website itself too.

One value I hope to establish is the concept of "upstream first" as a driving model for how we contribute. However, this means that we send regular Pull Requests the way of @somratpro. @somratpro, as the maintainer of the Upstream Theme, it would be helpful to know if you are interested in welcoming contributions from the @unicef Community, or if you prefer to keep the projects separate and distinct.

Closing criteria for this issue is new documentation in the Contributing Guidelines about how to contribute new changes and improvements to the Hugo Website theme.

Outcome

Documentation exists to guide new contributors on where to begin their contribution journey.

Summary

Develop a list of key themes about design in open source and map out new content fitting into those themes

Background

In the SustainOSS Design & UX Working Group, we have been talking for a while about documenting our learnings, conversations, and experiences in a more visible medium. I offered the UNICEF O.S. Inventory as a possible home for this documentation. We made a few steps towards collecting data for this documentation, like an open form for anyone to submit their favorite design resources. But as we discussed today, it would help to take a step back and look at our goal and purpose with documentation, and develop some key themes we want to explore first.

By defining themes, it will be easier for us to build and map out the content we actually want to share and publish. As @Memo-Es said, we all have resources, links, guides, and more that we always try to dig up, but they can be hard to find in the moment when we need them most! So, by developing some common themes, we can use this as a framing for what content we gather and build out.

Details

I propose these next steps:

1. @jwflory to create a first-pass list of themes based on content we have discussed in previous WG meetings and from the form submissions
2. Review list of themes in our next WG meeting (or asynchronously in this issue)
3. Map sub-topics or specific content we wish we had, or things we know of from others, that fit within the list of themes
4. Regroup on strategy for creating the content fitting into the identified themes

When we regroup, we can get more specific into answering questions like, "What article or knowledge do we want to share? Do we write it ourselves or create a list of other resources? What gaps exist in the O.S. design space that we could begin filling?"

Outcome

Path forward on documenting and sharing our learnings becomes more clear. It becomes easier to take first steps of creating new content.

CC: @Erioldoesdesign @Memo-Es @Nolski @mantas @georgiamoon @RichardLitt @jeepurs

Content classification

Is this about an existing page or a request for a new one?

Request for a new page, category, or section.
The title of the new content is: "Law & Policy", "Governance"

Content description

I propose breaking the "FOSS" category into two more specific categories. Currently, the content there focuses on licensing, policy and legal considerations, and governance. Additionally, "FOSS" is non-descriptive since everything in the Inventory is technically about Open Source.

This will make it easier to add guidance on trademarks in the future for the Acceleration Funding cohort joining the Innovation Fund soon.

When building open source design communities, the Ushahidi project has a repository which has some useful information pertaining to open source design.

https://github.com/ushahidi/opendesign

This is a meta issue to track the overall Outreachy internship project for May-August 2022.

Summary

There are two goals for the internship:

1. Improve UI/UX of the Inventory Hugo theme, so it is more responsive and user-friendly.
2. Redesign the existing categories to map to the Digital Public Goods Standard, and work with other UNICEF colleagues and UNICEF Innovation Fund start-up companies to get to know their challenges in complying with the Standard.

Background

Previous discussion and context

This is something we have been discussing for some time. Together with other members of the team (@acabunoc, @nathanbaleeta, @prajectory, @lacabra, and others), we started mapping what the restructure might look like in this Google Doc.

Technical breakdown: Open Source Inventory V.S. Inventory theme

During the internship, you will get to know two major components of the project: the UNICEF Inventory theme and the Open Source Inventory website.

UNICEF Inventory theme

The UNICEF Inventory theme is a general-purpose theme that anyone can use to create a new knowledge-base website. The theme is made for the Hugo static site generator tool. Anyone using Hugo can import the UNICEF Inventory theme into their project and use it for building a new website.

The theme is most prominently used on the Open Source Inventory website (explained below), but there are also other UNICEF projects and open source communities using the theme too. The UNICEF Inventory theme is a common "upstream" project for the different websites and projects using it. Changes and improvements made to the theme should benefit all downstream users.

Open Source Inventory website

The UNICEF Open Source Inventory is a knowledge-base of best practices, resources, and information about working and leading Open. This is maintained as part of the Open Source Mentorship program offered by the UNICEF Innovation Fund. The Open Source Inventory provides mentorship and guidance to anyone seeking to adopt best practices in their journey to building an Open Source project and community. It is self-serve and can be used at various phases of building a project and community.

At UNICEF, the Open Source Inventory is an important part of how we deliver guidance and coaching to UNICEF Innovation Fund companies. The knowledge-base is used to teach best practices about working on open source projects and how to launch your own project. The overall goal is to empower others with the knowledge and background they need to be successful in their open source projects. In other words, we want to help others build successful, inclusive, and sustainable open source communities!

The Open Source Inventory website is the most well-known Hugo site using the UNICEF Inventory theme.

Details

This section will be updated and modified as the application period comes closer. The best way to describe the general approach is in three parts:

• Improve UI/UX by tackling smaller issues in the backlog.
• Work with UNICEF colleagues and Innovation Fund start-ups to redesign the Open Source Inventory website around the Digital Public Goods Standard. This will involve UI/UX work but also working with the content hosted in the repository.
• Continue making UI/UX improvements after the redesign, with a focus on bigger and more challenging improvements. A new feature may be added as a stretch goal depending on intern progress.

Outcome

• The UNICEF Open Source Inventory is structured around the Digital Public Goods Standard and offers support material and guidance on complying with the Standard.
• The UNICEF Inventory theme is more user-friendly, responsive, and mobile-friendly.