---
# System prepended metadata

title: website-authoring-workflow

---

# Web Content Production Workflow

This document outlines our team’s workflow for producing, revising, and delivering web content. Currently most of what we do is based on informal but very familiar practices in the Learning Lab, but we can work towards more formal documentation if that's valuable. 

---

## 1. Evaluate

The first stage clarifies the scope and rationale for new or revised content.

* **Flesh out the ask(s):** Who is requesting this work, and why? Is it a Dean, a deadline-driven project, or dissatisfaction with current content? Identify the authoritative “to do.”
* **Inventory existing content:** Collect all relevant docs/pages, including live site content, Google Docs, and internal markdown files.
* **Map the current architecture:** Sketch how the existing section of the site hangs together. Identify gaps, redundancies, and problems.

**Format:**

* Description of the ask → written in text. Use HackMD if suitable for public consumption, or Google Docs if sensitive.
* Site map/architecture → done physically (on whiteboard or large paper). Often we print out relevant pages and lay them out in hierarchy.

---

## 2. Map & Plan

At this stage, we explore user journeys, peer practices, and a draft redesign.

* **User journey mapping:** Who is reading this content? Why? At what point in their workflow? Compare current vs. desired user experiences.
* **Peer benchmarking:** Examine how peer organizations or disciplines structure the same domain. Note mental models present in their site architectures.
* **Draft new architecture:** Sketch the revised structure. For each page, mark whether it is:
  * Existing and unchanged
  * Revised from existing
  * Brand new
* **Identify knowledge gaps:** What must we still learn? Look for relevant research, peer examples, or best-practice documentation.
* **Stakeholder involvement:** If appropriate, share the developed plan/map with key stakeholders and approvers—especially the original requesters.
* Clarify who is responsible for each task:
  * One person per doc?
  * One person for media, another for text?
  * Drafts supplied by leadership to be expanded?
* Tool stack choice
    * what tools are most appropriate for developing the content? who on the team is comfortable with which tools? let's determine which tools we'll be using for different steps in the workflow.

**Format/Tools:**

* Mapping and planning happen collaboratively (usually on paper on a big table or white board).
* But the developed plan and task lists must be captured in structured text so everyone knows their role. For teams comfortable with it, an Airtable Kanban is appropriate.

---

## 3. Research & Draft

Once roles are assigned, the work begins.

* **Research:** Gather relevant sources, media, and references.
* **Drafting:** Generate new text or revise existing material.
* **Media acquisition:** Collect or produce images, graphics, or other assets.

**Process:**

* Writing can take place in Google Docs or HackMD, but HackMD is preferrable for work with images and other embedded media. Simple scripts run at monthly intervals can sync up the various drafting zones and a single source of truth in Airtable.
* Incremental drafts are printed and reviewed in the collaborative work zone.
* Team lead monitors progress, identifies key moments to involve leadership, and seeks feedback only when necessary.
* All research and initial drafts should be archived for future use on related projects.

---

## 4. Revise, Revise, Deliver

Revision is iterative and involves progressively broader feedback.

* **Internal review:** Team members review each other’s drafts.
* **Team lead review:** Consolidates revisions and aligns voice and structure.
* **Leadership/external review:** Final input from requesters or external stakeholders.
* All members of the team should be able to directly edit the website. When working on a large-scale project, some division of labor is helpful, but we don't want to be constantly delegating minor technical tasks if it's faster for a given writer to do it him/herself.

**Delivery:**

* Final revisions are implemented and published.
* Documentation of decisions and final architecture is archived for reference.
* Maintaining the correct text on the website it the primary goal, but the source of truth exists in the Airtable database / Github.


---

# Open Questions

Here are some additional thoughts and questions.

* it's common to develop a style guide--we don't have one and manage norming style more informally
* drafting-file tools
    * **Google Docs** is very comfortable for people and is helpful for materials that might be sensitive (where we don't want to publish until the text is approved). But 
        * it doesn't enforce semantic markup
        * it isn't as LLM-ready as markdown
        * it doesn't enforce url-safe file naming
    * **HackMD** is great for collaborative markdown editing, which tends to enforce better media handling, naming conventions, linking behavior
        * but it is public
        * not everyone is currently comfortable with Markdown
    * **Github** would be ideal, but is even more challenging for non-technical people than HackMD
    * markdown *can* be held in **Airtable**, but Airtable is not a good authoring or previewing tool. Better for Airtable to contain a record per page (or other text asset) that then has a link to the document draft as well as the Bok webpage (if exists).
* image handling
    * stable public link for anything on the site? `#util-img-2-md channel` as example
* version control
* structured stages and review cycles in a Kanban?
* Pre-launch QA workflow/checklist
* lightweight RACI-type list of roles per doc/project? (who’s Responsible, Accountable, Consulted, Informed)
