Documenting Organizational Policies and Projects [Draft]

One of our core values is to #build-in-public and one of our core activities is to #share-information so it’s crucial for us to document our work for others to contribute to and learn from!

Questions

  • How might documentation be accessible?
  • Who needs what kind of documentation?
  • How do we limit noise when it comes to searching for documentation?
  • How do we encourage good documentation practices?

How do we document policies? (Out of Date Version)

Policies are things like role descriptions, guidelines, and workflows. Document policies by tagging them #faq (short for frequently asked questions). All #faq s are accessible by clicking on the tag, as well as from the hamburger menu.


Image Description: Screenshot of how to access the FAQ via the hamburger menu. To access the FAQ using only your keyboard, you can open the hamburger menu by using the = keyboard shortcut, or by using ⌘F + faq to find a #faq link.

You can also

How do we document meeting minutes?

Document meeting notes by tagging them #meeting-minutes. Use a format that works for you! Here’s a sample one that’s modified from Many Voices One Song: Shared Power with Sociocracy - #4 by TedRau. Key idea is to keep it simple and sweet.


Hi all, please review the meeting minutes and +1 if you consent or reply with your revisions!

Circle name:
Meeting date/time:
Attendance:
Updates:

  • elections
  • new policies
  • operational decisions

Next steps:
Upcoming agenda items:
Next meeting date/time:
Link to full meeting notes:


How do we document project updates?

Every #work subcategory is equipped with a Kanban Board view.


Image Description: Screenshot of Kanban Board view.

The Kanban Board View shows topic titles organized in columns under their respective project management tags.

#faq
#idea
#scoping
#ready (ideas that are ready to be acted on)
#in-progress
#evaluating
#sharing (thank people, announce the good news, make sure everything is documented)
#ongoing
#done

Use this board to track which tasks are in what stage. Topics can also be marked #blocked, which tells teams that they need to give the blocked task some extra attention in order to unblock it.

To learn more

How do I keep up-to-date with the work that I care the most about?

By default, we suppress topics in the #projects categories from the summary email. We also hide them from the /latest and /top pages so that people aren’t bombarded by these details. You can override these settings by using notifications. Read Discourse New User Guide: Notifications to learn more. For example, if you want to be notified every time a topic is posted in the #projects:online-forum category, you can choose ‘Watching First Post’ for that tag or category.


Image Description: Screenshot of how you can choose to “Watch” a category.

How do we document meetings?

See YPC Admin Calendar for Details.

So documentation as a whole needs some rethinking. Inspiration for how documentation could be structured comes from the Enspiral Handbook.

About This Handbook

This Handbook’s primary audience is Enspiral contributors, but it will be publicly available for others who might find it useful. The goal is to give everyone in the network as much clarity and context as possible, while sharing our structures and practices with the outside world as well.

This book is in perpetual beta, it’s constantly changing. If you see something that could be improved: that’s your invitation to improve it! Find out more about editing the handbook.

Structure

The book is broken up into chapters and sub-chapters. The chapters are:

Idea to Explore:

Instead of having policies be organized within circle categories and tagged #documentation, let’s flip it. Have a category for documentation (or call this logbook to align with sociocracy terminology), use sub-categories as necessary for separating out super technical documentation, and tag with the circle tags.

Example from Discourse

Update: I’m changing the tag “documentation” to “policy” instead because then it’s aligned with how policy is used in sociocracy.