Reconsider how the architecture and navigation on About can be made more welcoming for new users

[clausmullie]

1) Purpose of About

The Foundation for Public Code is an open organisation. Our ambition is to build a community around our work. To this end, all of our processes and documentation are open.

The community can be viewed from the perspectives of:

• maintainers - staff who rely on documentation for daily work, are the main contributors, and handle contributions
• contributors - community members who reuse parts of of our work and may contribute
• users - individuals who are interested in our work and want to learn more about how we do things and how it can help them

Our work can be thought of in two categories:

• internal operations - things that are unique to our organization (such as filing expenses, booking holidays or sending newsletters). These may be reused by others, but it is mainly documentation for staff, is linked to private platforms, and the main value of having this in the open is for transparency and trust
• delivery - things that we do that are not unique to our organization (such as supporting governance, running good community calls, or resources to support codebase auditing). These we actively strive to not only have others reuse, but also to get their contributions to make it better.

In line with open source best practice, we want to make our community as welcoming to new users as possible. This issue focuses on how to make our documentation more easy to understand and navigate. Being more open to new users will also encourage more contributions.

2) Background context

The core principle at the initial phase of creating documentation was to facilitate contributions (including predominantly markdown files in github, with reused and limited jekyll templating, and a simple index/resource/guide taxonomy for pages). This worked really well in the beginning. The organisation started with a tendency to make short pages in folder-like directories. This was a great way for staff to start building the organisation.

Once the organisation reached the size and complexity where silos developed (ie different directories starting to have duplicates of the same content) work was initiated to reduce the depth of directories - flattening activities in the activities index - to avoid the silo'ing of work and content. This was also a useful refactoring - one that we are continuing to do.

I think it now makes sense to revisit About and actively invest in making About user friendly to new users. New users being people visiting About for the first few times.

We have several anecdotal accounts of users being overwhelmed and lost when navigating About. Personally, I also feel the structure and navigating can be more welcoming. I would therefore like to rework About to a state that staff and community members can be proud of the quality of documentation and usefulness of About.

3) Taking a step back

It may be helpful to (re)consider three archetypes of structure and corresponding navigation.

Trees/branches

Much like a folder structure for files, this includes a page which links to nested pages which links to nested pages. I believe this works well for a collection of short pages - as either a storage system, or a carefully crafted user journey. As a storage system it's great for teams to create their own spaces and files to work together on. However, this tends to be very opaque for 'new users' (think of trying to find things on an old shared drive). As a carefully crafted user journey, it's great to address the most common needs first, and then allow the user to dig deeper into what they need. However, this requires a lot of crafting and thus maintenance.

The corresponding navigating is breadcrumbs. You can start somewhere, go deeper, and navigate back up once you have (or haven't) found what you were looking for.

Wiki

Pages with text with hyperlinks to other related pages. In my opinion this is great for exploring a large set of loosely related pages. However, precisely because if offers users a journey towards many different pages in many different places, it can be easy to get lost, feel overwhelmed, or not quite understand all that is available. This is great for something like the internet, which allows open ended exploration, or something like wikipedia, which has a large number of diverse pages (note: only ever 1 layer deep - ie each 'thing' has its own page, and is not nested, but linked from other pages) which can be however long and complex as they like. So I feel this works well for vast amounts of content that cannot be overseen, and requires either accepting the explore/getting lost tradeoff, and/or putting a tight structure in place.

The corresponding navigation is a search bar to find place to start, and in text links to surf deeper (with table of contents for longer pages).

Cookbook/menu style

Pages organised into categories/chapters - something like a cook book. I believe this works well to present a defined set of information, where the user can easily assess what is they might be interested in, go check the relevant page, and then come back to the menu(s). The strength and weakness of this is that it gives a structured index of what is available - users can get a sense of what is available, but decisions need to be made on what to include (and exclude) in the menu.

The corresponding navigation is a menu or table of contents.

4) Analysis of the current state of About

About is a mix of the three archetypes above. It is a collection of (mostly short) nested pages in relevant directories (tree/branch-style), with many hyperlinks to related readings (wiki-style), provides users with a sense of what is available through indices (cookbook-style), and this-page-contains on the top right to help people navigate the page.

In terms of navigation we have breadcrumbs on top, table of contents on the right, a search bar at the bottom, and indices and hyperlinks throughout.

It is my unverified assumption, based on anecdotal data, that About currently lacks a clear navigation system that new users can use throughout their journey. I would think of new users as people who have heard about us (at a conference, through a colleague, etc), wants to take a look at what information is there and find out whether it's useful to their work, and at a later point return to go deeper into the things they found interesting.

• Breadcrumbs - useful for staff to organise and store our resources, but less useful for new users as our documentation is not of the sort that is crafted for clear question-and-answer style navigation. New users will not know/remember how to navigate to different files (more for contributors/maintainers), and hyperlinks mean users can quickly move to a new tree/branch/page of which they don't know what else is there. Our directories are not very deep, so knowing which page is nested under which directory is not extremely valuable to new users.

• this-page-contains - not so useful in most cases as our pages are relatively short and our introductions usually recap what's on the page

• Hyperlinks - useful to help everyone navigate off into connect relevant resources, but other than the 'back' button, offers little help in navigating the totality of the content. Helps new users dive into the content, but doesn't help them situate themselves in relation to the content.

• Indices - helpful to get an oversight of everything that is in that directory, but once I navigate deeper, or follow hyperlinks, I'm quickly lost into the content. Helpful to get a perspective what's in the directory, but gives on oversight over the whole.

• Search bar - useful if I know what I'm looking for, or if what I expected from a particular page wasn't there. Does help introduce me to what is there.

5) Reflections on possible changes that could be made

About currently follows a very modular and componentised architecture. Pages are kept short, discreet and specific, linked to from indices and other pages. This component-based approach is highly effective in reducing long term maintenance. Pages can grow at their own pace, don't intersect with each other, and don't need to be intertwined with other pages. For example, a page on certification explains only certification, as it linked to from stewardship, auditing, and the standard. It remains easy to edit, if moved can be redirected, and other pages that link to it can be edited independently.

However, this component based approach comes at a trade off of pushing cost and complexity onto the reader. A reader is not served a nice logically flowing page or story, but rather has to navigate into an index, read something, open two or three links to go read them, find their way back to the original index, and then compile these components in their mind before having a clear idea of the information that is being provided.

Example of modularity - codebase auditing index and #1111 Example of consolidating modularity for readability - stewardship index work in #1077

I would like to raise two points for consideration:

1. Content architecture - I think we should invest more in the ease of readibiliy of our information, to make it easier to understand, more welcoming for new users, and thus more effective, more likely to have a higher impact, and reach a wider audience. This can come at the cost of putting more burden and cost on the maintainers and overall maintainability of the repository. We should find a balance, of course, but err on the side of readability.

2. Content navigation - I think we should invest in providing our (new) users with as helpful navigation tools as possible in order to a) minimise the overhead cost of 'compiling' components of information into a sensible narrative in their minds, and b) reduce the friction in their experience of navigating about.

Content architecture

1. Set intention to make indices readable and informative.

This may include setting an intention to keep directories shallow (so for example try avoid anything deeper than 4 levels; about/activity/[name-of-activity]/[index] & about/activity/[name-of-activity]/[resources/guides-needed-for-it]. Everything with more depth should most likely be refactored to separate activity/organisational atribute or merged into the index one level up

This is also inline with our documentation structure; indexes should explain the activity, supported by resources (like templates) and guides for how to do it. In other words, if it is not strictly a resource or a guide, it should be the index. Resources should not be used to explain new content, only be a tool to help execute it.

Perhaps there are valid exceptions, but setting this intention should keep us on our toes

This will also provide an incentive for us to avoid deep and complex trees (silos) and keep a reasonably flat hierarchy. This will improve legibility for new users, but also contributors and maintainers.

Note: this does reinforce the modular component approach on the 3rd level (so about/activities/[component] and about/organization/[component] directories become a collection of discreet components) but reduces this approach at the 4th level (so a component shouldn't be made up of more components, only the index and resources+guides)

Navigation features on About

1. Consider introducing a navigational menu on the side (remains available throughout journey on all pages). For example see dna.crisp.se and docs.opencollective.com Menu goes 2 levels deep (So heading 'Activity' and under that a list of all activities, but no further) If technically possible, we could consider expand/collapsing items here, but not necessary for now I think -> This provides users with a clear idea of what types of information are available, a sense of continuity in their journey, and the ability to jump between items without getting lost. It also provides us an incentive to give pages titles intuitive to new users. This means users are never more than 1 step away from a place they can find through the navigational menu.

2. Reconsider need for breadcrumbs Flatter hierarchies and a navigational menu would remove the need for breadcrumbs, as navigational menu provides enough oversight, never more than 2 deep. -> This will help declutter the page.

3. Remove large About the Foundation for Public Code call to action on top of page the need for a return home button is removed with the navigational menu. This index will be easily accessible through the navigational menu. -> This will help declutter the page.

4. Consider how often we use hyperlinks Particularly on pages with multiple calls to actions and hyperlinks link to the same page (ie a page with 4-5 links leading to /activities/codebase-stewardship). While there may be good reasons to this sometimes, it can also be distracting to a new user who may think they lead to different things. It may be good to hyperlink to it once in the beginning of a paragraph/section, and then leave the other mentions unhyperlinked (similar to how academic references have a reference with first mention, and then just state name and year unless a specific page number is needed). -> with less links to other pages/content, it may give people a greater sense of focus when reading the content of a page.

5. Reevaluate need for This-page-contains if we would like to stick with short pages, we can remove this as clutter. If we would like to work towards longer pages, this will be more helpful. My sense is that with the changes above, we will go towards longer pages.

Note: these navigational changes would also allow the rewriting of the activities/index and organization/index. I would welcome them having more explanatory information instead of a long list of links (which can now be accessed via navigational menu).

Note: these changes would be done on the jekyll theme which is used across (almost) all pages. These changes would not be beneficial to other repositories, expect perhaps the standard, where it could add value.

6) Additional housekeeping

We could also consider doing some work to declutter the user interface of About.

Things we could consider: 6.1) Remove duplicate call to action to make issues/pull requests on github [Contribute on Github and This site on github are near identical, with the latter linking to https://github.com/publiccodenet/about twice consecutively] 6.2) Remove duplicate last updated and last published 6.3) Remove duplicate copyright and license information 6.4) Reevaluate whether contact and organizational notes needs to be in footer, or whether a call to action + hyperlink to this information is enough.

-> with less clutter around the content, it may give people a greater sense of focus when reading the content of a page.

7) Potential next steps

This is not my area of expertise, so I'm curious to hear what others think.

In any case, this refactoring should be done in many small and incremental steps, such as:

• decluttering work can be done separately from the content
• deep trees can be refactored into more shallow directories
• test branches can be made to play around with navigational options
  • once a potential navigation solution has been found, attempt to refactor one larger index to assess what the pain points/effort would be to refactor all of About

---

edit: thanks @Ainali for your feedback! :)

[clausmullie]

After some more thought and discussion, another consideration might take precedence over this.

I think we should invest more in the ease of readibiliy of our information, to make it easier to understand, more welcoming for new users, and thus more effective, more likely to have a higher impact, and reach a wider audience. This can come at the cost of putting more burden and cost on the maintainers and overall maintainability of the repository.

This is not necessarily a valid approach.

About can be modelled on two ideas:

1. A set of functional 'how-to' guidelines for staff to execute their work, which can be made open for others to browse if they would like to
2. A set of informational resources that explain what the Foundation does to new and uninitiated users

The how we work call to action on our homepage and documentation guide tend towards the former, while the About naming tends towards the latter. We currently have a mix of pages that serve up dry lists of practical processes (the former approach) and pages that try explain what we do to a new audience (the latter approach). This mix is quite confusing.

If we can take a clear decision that it is the former, most of this issue can be ignored. In this case, we should make this point stronger in documentation and remove explanatory content from indices. If we do decide it is somewhere in between, we need to develop clear and understandable principles and guidelines for when to do what.

In reworking the codebase stewardship the following pattern made most sense:

• activities/codebase-stewardship contains all the processes a codebase steward would need to execute on their role
• activities/explaining-codebase-stewardship contains all the information needed to explain stewardship to a new user

We could consider a similar pattern for anything that needs explaining to a new user (ie governance, auditing, membership & partnership,...)

[clausmullie]

About can be modelled on two ideas:

1. A set of functional 'how-to' guidelines for staff to execute their work, which can be made open for others to browse if they would like to
2. A set of informational resources that explain what the Foundation does to new and uninitiated users

However, as an organization with the ambition to be an open and community-driven organization, the art may be to navigate the middle line in this dichotomy carefully.

Another approach could be:

• publiccode.net contains all the introductory information aimed at a uninitiated user unfamiliar with our orgnization
• about.publiccode.net contains all the how-to style documentation on practical execution of processes, so assuming familiarity with the organization and it's processes to declutter and enable efficient communication between those doing the work
• each index on about.publiccode.net contains a short paragraph orientating a new reader to what is on the page
• any other explanatory content on about.publiccode.net is included in activity/explaining-activity.md

This would offer some sign posting, while limiting the scope screep of this ambition into operational documentation (and the cognitive dissonance that comes with it). A clear rule of thumb like this would also limit the amount of time/energy/complexity of reconsidering this balance with each page/change.