civicactions / guidebook

The home of policies and guidelines that make up CivicActions

title	hide
CivicActions Guidebook	navigation toc

Guidebook Purpose

This Guidebook has been prepared to describe the CivicActions philosophy, working methods and processes, employment practices, policies, benefits, and conduct we expect from members of our team.

Common Topics

• :fontawesome-regular-calendar:{ .lg .middle } Holidays

  ---

  Find out when CivicActions is closed

  :octicons-arrow-right-24: US holidays :octicons-arrow-right-24: Canadian holidays

• :fontawesome-solid-laptop:{ .lg .middle } Technology stipend

  ---

  Employees get annual funds for technology

  :octicons-arrow-right-24: US tech stipend :octicons-arrow-right-24: Canadian tech stipend

• :fontawesome-regular-credit-card:{ .lg .middle } Expense requests

  ---

  How to get reimbursed for business expenses

  :octicons-arrow-right-24: Out-of-pocket expenses

Contact Information

CivicActions, Inc. 3527 Mount Diablo Blvd., Unit 269 Lafayette, CA 94549

510.408.7510 | main 888.714.7388 | fax civicactions.com

License

Copyright 2017-2024 CivicActions.

This work is licensed under the terms of the Creative Commons Attribution 4.0 International (CC BY 4.0) license.

Acknowledgements

We'd like to thank the folks at 18F for their handbook, from which this documentation was forked. We welcome you to fork our documentation, or use the 18F handbook, which is licensed as CC0.

guidebook's Issues

Got a few pages with links that have double (and more) anchors

See https://github.com/CivicActions/handbook/pull/984/files, need to fix those links to only have one anchor.

Fix link to harassment policy on Culture page

On the Culture page, there's a 404 error for the link "Policy Against Proscribed Harassment and Discrimination near the bottom of the page.

Acceptance Criteria

• Link to the harassment policy is https://handbook.civicactions.com/en/latest/040-employee-handbook-us/anti-harassment-policies/#policy-against-proscribed-harassment-and-discrimination

Insecure recommendation in Screen lock ("Securing Your Workspace") documentation

In https://guidebook.civicactions.com/en/latest/common-practices-tools/security/securing-your-workspace/

you suggest

xss-lock -- i3lock -n -c 000000

exec --no-startup-id xss-lock -- i3lock -n -c 000000

That, however, is not the recommended procedure to ensure screen is locked on suspend, because the call to xss-lock is missing the argument --transfer-sleep-lock to xss-lock. See the help of i3wm itself: https://github.com/i3/i3lock?tab=readme-ov-file#running-i3lock and additional discussion here i3/i3lock#207 (argument "-l" and "--transfer-sleep-lock" are the same).

Accessibility issues to resolve

There seem to be a few accessibility errors with the handbook.

FastPass_20231025_CivicActionsGuideboo.html.zip

ARIA, Color Contrast and keyboard accessibility issues.

"CivicActions Handbook Home" should land on README

Clicking on "CivicActions Handbook Home" (in the upper left) brings you to Docs >> LICENSE while README would seem a better landing place.

Set up common Video Call Best Practices section

The Video Call Best Practices should be its own section in and not be within Google Meet (formerly Google Hangouts)

Some of this is specific to Google, but in general we'd like to highlight how to do a good video call.

Video Call Best Practices

• Be on time - please! Every 10 seconds actually matters
• Default to video on for all video meetings
• Add a photo to your account so it shows up in Google Meet if your camera is off
• We use the chat and screen sharing features
• Turn off your camera or reduce bandwidth if connection is poor
• Use some kind of headset or headphones instead of relying solely on computer mic (computer mics can sometimes create echoes)
• Use proper etiquette for video call professionalism (consider the appropriateness of background visuals/noise, attire/dress, use of effects, eating, muting, etc.)
• It's okay to mute others or ask them to mute themselves
• We can invite people outside of CivicActions
• If someone hears an echo & you don't, then it's likely your computer creating the echo. Try using headphones or plugging them in again
• Use screen sharing for demos and for pairing

Link checker reporting URLs as not available (status 0 or other statuses) when they are actually available

It seems that the link checker is running into sites that report status: 0. I am not sure if it is a timeout issue or the site is blocking the bot. On a retry the error usually clears but it would be nice to maybe have checker retry automatically or potentially not be so onerous.

Change /images folder to /img

This is the only way the favicon.ico file will display in the browser. Alternative is to add a folder just for this file if it's going to break all the other images.

Disable read the docs flyout menu

Not useful anymore, best to disable it for now.

Consider adding a section for managing government furnished equipment

Given the number of contracts we have that require work on GFE, we might want to have a section dealing with how to manage GFE (and return at the end of a contract or end of employment)

Added underline text decoration for links in the content

Request from @mgifford

Duplicate search results

A search for “tech stipend” returns duplicate results for 4 pages. This happens for some but not all pages in the handbook when searching for content.

We need to investigate this bug or setting that could be tweaked to return only 1 result.

Update Referral policy page

I'd be willing to make a pull request myself but I'm so new and I don't really know what the policy on this is. 

This page is about how to send an employee referral and the policy surrounding that etc: https://handbook.civicactions.com/en/latest/030-policies/employee-referral-bonus/

We now have greenhouse though so I think we could update it to include guidance on using the greenhouse referral links. Those make things waaaay easier.

Add documentation/instructions on updating navigation for editors

We need a helpful guide to let editors know how to update the site navigation https://github.com/CivicActions/handbook/blob/master/.config/mkdocs.yml#L36 including adding new items, removing old ones (when deleting a page), and handling child menu items.

Links:

• https://www.mkdocs.org/user-guide/configuration/#nav
• https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/

Add support for markdown tables

Right now markdown tables can complain about spacing issues (see retextjs/retext-sentence-spacing#9). We can install something like this https://github.com/remarkjs/remark-gfm but we also still want our regular checks to occur within a table which I am not does with that. Needs more testing.

Proof of concept, submodule markdown files from another repo

Test out whether markdown files can come from a separate repo and rendered in the guidebook.

Improve readability of guidebook navigation labels

In #1088 we updated the guidebook top navigation to increase the font color contrast and font size. In doing so the space between the labels is smaller, thus reducing readers' ability to differentiate between the labels.

To correct this, we’re changing the navigation labels using words with equivalent meaning and fewer characters:
Home
About us
Employee benefits
Company policies
Our practices and tools
Practice areas
About this guidebook

A PR will be created the week of April 24 to make these changes.

Accessibility issues

Review and fix accessibility issues in the handbook:

• Missing form label on the search form. Bug appears to be the core theme https://github.com/readthedocs/sphinx_rtd_theme, so good to fix it there if possible.
• Contrast errors (this will need input from design).

Wave report: https://wave.webaim.org/report#/https://handbook.civicactions.com/en/latest/

Delete 080 folder per content audit

Add instructions to configure git commit signing to the guidebook

Potential location is https://guidebook.civicactions.com/en/latest/common-practices-tools/security/encryption/

Switch to github issues from Trello

Broken link: Backend Development > Drupal-specific Coding Standards

Link "The Most Important Decision In Developing A Drupal Site: Contributed Vs. Custom Development" results in 404. Guessing we took this blog post off our Medium page.

Beta site header changes

To do, make changes to the beta site (material theme, see #926)

• Change colors (change beta banner background color to A23737, change search box background color to D83933)
• Change the icon, remove the icon
• Change table of contents to say 'On this page'
• Add '- Beta' to the site title and change to 'Guidebook'

Unfork from 18F/handbook to enable search from Github UI

Not a huge deal, but we can't perform searches on forked repos from the github UI.

Known workarounds:

1. search in gitlab
2. search in RTD

Mark GitHub repo "releases" for significant changes to the handbook

When significant changes are made to the handbook, can it be tagged as a new release/version? For added goodness, have the creation of the new release be posted to slack so people know to look for the changes.

I ask because right now, there is no way to know when (like say the changing to the current-events channel or more recently, the new tech reimbursement policy). I've found out about some changes that were officially live in the handbook only after being verbally told of them... even though I had already heard in AHC that they were "being worked on". This has happened to me multiple times, most recently this week about the tech stipend.

Following the GitHub repo for changes is too noisy, as there are so many other changes for typos and smaller non-significant changes. In GitHub, when following a repo, you can choose to only be notified of "releases". This would be perfect. But it requires a human to tag a new release - and it looks like we have not done this.

Not sure who to ask, hence creating this issue to track.

Purpose of the asterisk at the end of each of the holiday dates

guidebook/employee-benefits/README.md

Line 15 in ea0dc43

| New Year's Day | January 1st\* |

Looking at the holiday schedule, I noticed an asterisk at the end of each of the dates. I tried looking for some details around the page that is in reference to those asterisks. Couldn't find anything. Maybe we should remove them?

See below for those asterisks.

| Holiday                             | Dates                         |
| ----------------------------------- | ----------------------------- |
| New Year's Day                      | January 1st\*                 |
| Birthday of Martin Luther King, Jr. | Third Monday in January       |
| Memorial Day                        | Last Monday in May            |
| Juneteenth                          | June 19th\*                   |
| Independence Day                    | July 4th\*                    |
| Labor Day                           | First Monday in September     |
| Veterans Day                        | November 11th\*               |
| Thanksgiving Day                    | Fourth Thursday in November   |
| Day after Thanksgiving              | The Friday after Thanksgiving |
| Christmas Day                       | December 25th\*               |

Style Guide Update

In our handbook, we are using a mix of title case and sentence case capitalization. What is the preferred way and can we update the style guide?

Broken link to EFF intro

@alanna-casey and @openprivacy

On this page https://guidebook.civicactions.com/en/latest/common-practices-tools/security/encryption/, the link to https://ssd.eff.org/module/introduction-public-key-cryptography-and-pgp is going to 404 now in the below paragraph snippet.

If you'd like some background on how encryption works, start by reading An Introduction to Public Key Cryptography and PGP, a Surveillance Self-Defense (also an excellent read) tutorial from your friends at the Electronic Frontier Foundation [Donate!]

Do you have a recommendation for a suitable replacement?

Broken link on Zoom page

https://handbook.civicactions.com/en/latest/050-how-we-work/tools/zoom/

There is a link on this page:

download the Zoom browser extensions

Which leads to a 404. I would try to put in a fix myself but I am not sure where it is meant to point to.

Add nav reviewer for changes to mkdocs.yml

Any PRs that would change the guidebook navigation must be reviewed by a content designer. For the initial period, @ContentBrewmaster will review the PRs.

Script to update paths to new structure

This is planned and we want it to be an atomic change so we can handle redirects etc at the same time

Add "Updated on [date]"

https://trello.com/c/peKzS4qh/333-add-updated-on-date-programmatically

To build trust that content is accurate, we want to display the date the content was last updated.

Update references to MFA

A recent gov client security assessment revealed that we need to be consistently referring to MFA -- not TFA, 2FA, two-factor, and two factor. Handbook should be updated accordingly.

The handbook sitemap.xml is referencing branches, causing broken links in google search

A random issue I stumbled upon. It appears that the sitemap.xml (https://handbook.civicactions.com/sitemap.xml) for the handbook is only listing links to various branches. I am guessing that Google is then indexing the pages from that link and generating links that no longer work.

An example of the issue (worked on Jan 29, 2021):

• Search for site:civicactions.com agile
• The first result is the page with the title 'Agile Overview - CivicActions Handbook'.
• The URL is https://handbook.civicactions.com/en/akaroleff-patch-4/04-how-we-work/agile-overview/ which does not load.

Probably best would be that the sitemap.xml does not include branches and if possible include all actual pages under the latest branch.

Have dependabot track mkdocs insiders (somehow?)

Question for @grugnog on whether dependabot can track mkdocs insiders and keep that version updated? What do you think?

Add Google analytics

Add Google Analytics to this code:

google_analytics: ['UA-xyz', 'URL']

Here:

https://github.com/CivicActions/handbook/blob/master/mkdocs.yml

Wave a11y report errors for material theme

Wave is reporting a lot of errors for the material theme (currently 34 errors https://wave.webaim.org/report#/https://handbook.civicactions.com/en/latest/ and 8 contrast errors when using the browser tool).

To dos

• Fix contrast errors in the "read the docs" popup that allows switching of branches.

Follow-up on the Wave a11y errors (see quote below from #926)

Looks like the a11y issues are known:

• squidfunk/mkdocs-material#4006
• squidfunk/mkdocs-material#3156

For the keyboard navigation for sub-topics one option is enabling navigation sections and navigation expansion (https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-sections). We can also introduce tabs, if we overhaul the menu. Right now all top level pages would be tabs and that is a lot of tabs.

Add a Front End practice area page under Practice Areas / Engineering

We need a page detailing information about the front end practice area. This should include meeting details, relevant slack channel, and link to a (cleaned up 😄 ) Trello board where more information on the latest initiatives can be found.

cc: @iris-i @dcgoodwin2112

Needs updating: "How and when to contribute to the handbook"

All the information about Trello seems to be outdated. The Trello board doesn't exist. Also not sure if there's a documentation working group.