Skip to content

Latest commit

 

History

History
204 lines (135 loc) · 7.25 KB

README.md

File metadata and controls

204 lines (135 loc) · 7.25 KB
Raw

📓 🚧 Documentation

{% hint style="info" %} ShortURL | Playbook | Assistant {% endhint %}

{% hint style="success" %} This Handbook responds to the following Policies:

  • Information Management
  • Intellectual Property {% endhint %}

About

This document provides all the guidance to produce documentation for The IO Foundation and its initiatives.

{% hint style="warning" %} In this documentation, the term Entity refers to either:

  • The IO Foundation
  • An organization member of The IO Foundation's Network
  • An initiative run by any of the above {% endhint %}

The tools

The IO Foundation relies on the following tools to provide its documentation services:

Type Product Usage
Documentation Manager Gitbook Consolidates all the documentation across all the platforms.
Documentation storage Github Stores all the documentation.
Short URL manager Bl.ink Provides with reusable shortURL to important documentation pages.
Playbooks Dooly.ai Provides an easy way to access relevant documentation when taking Notes.
Assistant Typebot Provides an interactive interface to assist with tasks described in the page.

Documentation conventions

Space Structure

In the interest of consistency, The IO Foundation structures its documentation following this structure:

  • About
    Provides all the information needed to understand this Entity and its objectives.
    • Introduction
      Explaining what this Space is about.
      • Theory of Change
        Explaining what is the identified problem and what is the proposed solution.
      • Business Plan
        Explaining the details on the Business Plan for this Entity.
      • Status
        A quick overview to the current implementation status of this Entity .
      • Repository
        Explaining the structure of the repository hosting this Entity .
      • Media Kit
        Providing all the necessary Comms information for this Entity .
      • Terminology
        Providing definitions for all the specific terms used in this Entity.
      • Frequently Asked Questions
        Answering some of the most common doubts related to this Entity.
    • Join Us
      Explaining how to join and collaborate with the Entity.
    • Support Us
      Explaining how to support the advancement of the Entity.
    • Acknowledgements
      Indicating specific recognitions to notable contributors to this Entity.
    • Media Archive
      Listing the mentions this Entity has had in media over time.
  • Institutional
    Provides all the information relative to organization and guidance for this Entity.
  • Research
    Provides all information relative to research undertaken in this Entity.
  • Operations
    Provides all the information relative to the implementation of this Entity.
  • CUSTOM
    Depending on the needs of the Entity, custom sections will be made available.
    An explanation of these will be provided in the Introduction page of the Entity.

{% hint style="warning" %} Some variations may happen depending on the specific needs of the Entity.

Equally, each of these sections may have sub-sections according to the specific needs of the Entity.


Please refer to the corresponding Space Structure section on the corresponding Entity. {% endhint %}

Page Structure

The Quickbar

Most pages offer a Quickbar at the top providing with relevant shortcuts to:

  • The ShortURL for the page
  • The Playbook linking this page
  • The Tarian Assistant for this page

Template

{% hint style="info" %} ShortURL | Playbook | Assistant {% endhint %}

Shortcut Status

Shortcut Status Description
Shortcut Active This shortcut is ready to be used.
Shortcut Inactive This shortcut hasn't been configured.
Shortcut Not applicable This page does not have this shortcut type.

{% hint style="info" %} When one of the shortcuts is not an active link, the information may be missing.
Please report it. {% endhint %}

Iconography

Page Status

Indicates in which

Icon Meaning
🚧 Work In Progress


Pages that are empty will have a notice as shown below.
👌 Usable
👍 Ready to publish
🔥 Hot topic Pages that have recently been created, updated
🗑️ Requesting deletion

<OTHER>
(See Page Type)

 Published

{% hint style="warning" %} NOTICE

This documentation page is under construction.
Should you want to be notified once it's published, let us know. {% endhint %}

Page Type

Once a page is Ready, its icon signals the type of information it contains and the audience it is meant for.

Icon Meaning Description
🎯 DCDR Key concept Contains concepts that are core to the DCDR advocacy.
Policy
📓 Handbook
📢 Comms Contains information relevant for communications.
⚙️ Technical Contains technical reference information.

Maintenance

Proposing a change

Proposing a translation

Formatting

Enunciations

When listing a number of items in a sequence, avoid using a coma (,) before the last one.

Example

Preferred: Tom, Luisa and Jenny when to first to the mountain, then to buy ice cream and finall back home.

Lists

When listing a series of items, do not end them with punctuation unless it's a question.
As a general rule, try to avoid exclamation marks.

Example

  • This is one item
  • This another item
  • Maybe this would be a third item?
  • I am sure this is the fourth!