WIP split into categories

assets/scss/base/list.scss

@@ -1,9 +1,8 @@
 .list {
     .container {
         display: grid;
-        grid-template-columns: repeat(auto-fit, minmax(240px,1fr));
+        grid-template-columns: 1fr;
         gap: 1em;
-        align-items: start;
     }
     .list-item {
         color: inherit;
@@ -19,6 +18,7 @@
         }
         &__summary {
             margin-bottom: 1.5em;
+            line-height: 1.4;
         }
         &__date {
 

assets/scss/base/page.scss

@@ -1,8 +1,4 @@
-.page-title {
-	font-size: 1.5em;
-	@media (min-width: 600px) {font-size: 2em;}
-}
-
+.page-title {font-size: 2.5em;}
 .page {
 	font-size: 1em;
 	@media (min-width: 600px) {font-size: 1.25em;}
@@ -28,6 +24,42 @@
 	.meta {
 		grid-area: meta;
 	}
+	.page-summary {margin: 1em 0;}
+	.page-cover {width: 100%;}
+
+	h1,h2,h3,h4,h5,h6 {line-height: 1.2; margin-bottom: 1rem;}
+	p {
+		line-height: 1.4;
+		margin-bottom: 1em;
+	}
+	h1 {font-size: 2.49em}
+	h2 {font-size: 2.07em}
+	h3 {font-size: 1.728em}
+	h4 {font-size: 1.44em}
+	h5 {font-size: 1.2em}
+	h6 {font-size: 1em}
+
+	blockquote {
+		font-size: 1.5em;
+		@media (min-width: 600px) {font-size: 2em}
+		margin: 1em 0;
+		font-family: serif;
+		border-left: 0.25rem solid black;
+		padding-left: 0.5em;
+	}
+
+	pre {
+		font-family: monospace;
+		background: #333;
+		color: white;
+		padding: 1em;
+		line-height: 1.4;
+		overflow-x: scroll;
+		margin-bottom: 1em;
+	}
+	ul {list-style: disc; margin: 1em 0;}
+	li {margin-bottom: 1em; line-height: 1.4; margin-left: 1em;}
+	ol {list-style: number; margin: 1em 0;}
 }
 
 .tags {
@@ -38,6 +70,14 @@
 		list-style: disc;
 		border-radius: 4px;
 		margin-left: 1em;
+		margin-bottom: 0;
 		a {color: inherit;}
 	}
+}
+
+#TableOfContents {
+	list-style: none;
+	margin: 2em 0;
+	li {margin-bottom: 0; margin-left: 1em;}
+	a {color: inherit;}
 }

assets/scss/base/typography.scss

@@ -1,7 +0,0 @@
-h1,h2,h3,h4,h5,h6 {line-height: 1.2}
-p {
-    line-height: 1.4
-}
-
-
-#projects, .page-title, .site-nav {text-transform: lowercase;}

assets/scss/main.scss

@@ -1,6 +1,5 @@
 @import "base/reset.scss";
 @import "base/sections.scss";
-@import "base/typography.scss";
 @import "base/page.scss";
 @import "base/list.scss";
 

assets/scss/partials/site-header.scss

@@ -10,7 +10,7 @@
 
 .site-masthead {display: flex; align-items: center;}
 .site-icon {width: 44px; height: 44px; border-radius: 100em; margin-right: 1em;}
-.site-title {}
+.site-title {margin-bottom: 0; line-height: 1; font-size: 1em;}
 
 body {margin-bottom: 64px; min-height: calc(100vh - 64px)}
 
@@ -30,7 +30,7 @@ body {margin-bottom: 64px; min-height: calc(100vh - 64px)}
 		display: flex;
 		justify-content: space-around;
 		li {
-			flex-grow: 1;
+			flex: 1;
 			border-bottom: 4px solid #212121;
 			&.active {
 				font-weight: 700;

config.toml

@@ -17,17 +17,23 @@ name = "Home"
 url = "/"
 weight = 10
 
+[[menu.main]]
+identifier = "experience"
+pre = "<i class='fa fa-briefcase' aria-hidden='true'></i>"
+name = "Work"
+url = "/work/"
+weight = 20
+
+[[menu.main]]
+identifier = "code"
+pre = "<i class='fa fa-code' aria-hidden='true'></i>"
+name = "Code"
+url = "/code/"
+weight = 30
+
 [[menu.main]]
 identifier = "blog"
 pre = "<i class='fa fa-pencil' aria-hidden='true'></i>"
 name = "Blog"
 url = "/blog/"
-weight = 20
-
-[[menu.main]]
-identifier = "casestudies"
-pre = "<i class='fa fa-address-card' aria-hidden='true'></i>"
-name = "Case Studies"
-url = "/case-studies/"
-weight = 30
-
+weight = 40

content/blog/elements/index.md

@@ -0,0 +1,43 @@
+---
+title: "Elements"
+summary: "Testing styles"
+draft: true
+---
+
+# h1
+## h2
+### h3
+#### h4
+##### h5
+###### h6
+
+"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
+
+> "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
+
+- Lorem
+- Ipsum
+  - Dolor
+  - Sit
+- Amet
+
+1. one
+1. two
+    1. two point 1
+    1. two point 2
+1. three
+
+```
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Lorem ipsum
+    dolor sit amet,
+    consectetur adipiscing elt
+        sed do
+            eiusmod
+            tempor
+            incididunt
+        ut labore
+        et dolore
+    magna
+aliqua.
+```

content/case-studies/_index.md

@@ -1,3 +0,0 @@
----
-title: "Case studies"
----

content/case-studies/mastodon/index.md

@@ -1,10 +0,0 @@
----
-title: "Mastodon documentation revamp"
-summary: "Reorganizing the documentation for the Mastodon Project, while also rewriting significant portions of it."
-date: "2020-01-04"
-tags: ["mastodon", "documentation", "information architecture", "rest api"]
-cover: "cover.jpg"
----
-
-Eugen Rochko, Mastodon project lead:
->bless you for being here to work on the docs btw. it's a big relief.

content/case-studies/pixelfed/index.md

@@ -1,2 +0,0 @@
----
----

content/code/_index.md

@@ -0,0 +1,3 @@
+---
+title: "Coding projects"
+---

content/work/_index.md

@@ -0,0 +1,3 @@
+---
+title: "Work I've done"
+---

content/work/mastodon/index.md

@@ -0,0 +1,204 @@
+---
+title: "Mastodon documentation revamp"
+summary: "Reorganizing the documentation for the Mastodon Project, while also rewriting significant portions of it."
+date: "2020-01-04"
+tags: ["mastodon", "documentation", "information architecture", "rest api"]
+---
+
+## Overview
+
+The project had two phases -- first, I had to identify what was missing or could be improved from the old docs; second, I had to come up with a new structure and write all that documentation.
+
+## Information architecture
+
+### User guide
+
+```
+Old structure: "User Guide"
+- Basics
+- Decentralization
+- Privacy
+- Moderation
+
+New structure: "Using Mastodon"
+- Signing up for a new account
+- Setting up your profile
+- Posting toots
+- Using the network features
+- Dealing with unwanted content
+- Promoting yourself and others
+- Set your preferences
+- More settings
+- Using Mastodon externally
+- Moving or leaving accounts
+```
+
+Many of the pages in the old user guide did not actually deal with teaching people how to use Mastodon, so the content within them was reworked into a more general landing page that explained the benefits of Mastodon. This new landing page explains the basics of microblogging and federation, before moving into the practical implications that these decisions have for user freedom, privacy, and safety. Select quotations were included from previously published promotional material on the Mastodon blog.
+
+After this, an entirely new user guide was outlined from scratch, covering the user life cycle from start to end (or new beginning).
+
+### Admin guide
+
+```
+Old structure: "Admin guide"
+- Installation
+- Configuration
+- Post-installation steps
+- Scaling up
+- Optional features
+- Upgrading to a new release
+- Migrating servers
+- Troubleshooting
+
+New structure: "Running Mastodon"
+- Preparing your machine
+- Installing from source
+- Configuring your environment
+- Installing optional features
+- Setting up your new instance
+- Using the admin CLI
+- Upgrading to a new release
+- Backing up your server
+- Migrating to a new machine
+- Scaling up your server
+- Moderation actions
+- Troubleshooting errors
+```
+
+This section was mostly straightened out already, but could still use some improvements. A pre-installation page was split out from the old installation page. Backup instructions were moved out of "Optional features" and into a dedicated page. Pages were added for moderation and CLI usage.
+
+### Development guide
+
+```
+Old structure: "Development guide"
+- Overview
+- ActivityPub compliance
+
+New structure:
+"Contributing to Mastodon"
+- Technical overview
+- Setting up a dev environment
+- Code structure
+- Routes
+"Spec compliance"
+- ActivityPub
+- WebFinger
+- Security
+- Microformats
+- OAuth
+```
+
+The old "overview" page contained a mixture of information about setting up a dev environment, libraries used, code structure, and useful commands to run for testing.
+
+The first step in cleaning this up was to split this page into multiple discrete pages, each with its own purpose. As "development" is a vague term, two new sections were created to replace it: one for client development (merged with API), and one for server development. The old "overview" pages were nested under the server development section, as they dealt primarily with server development.
+
+Next, "ActivityPub compliance" was moved into a dedicated section for spec compliance, and pages were created for documenting how various significant specifications were used and implemented within Mastodon.
+
+### API
+
+```
+Old structure:
+"API overview"
+- Guidelines
+- Libraries
+- Authentication
+- Permissions
+- Entities
+- Parameters
+- Streaming API
+- Web Push API
+"REST API"
+- Accounts
+- Apps
+- ...
+- Timelines
+
+New structure:
+"Developing Mastodon Apps"
+- Getting started with the API
+- Playing with public data
+- Obtaining client app access
+- Logging in with an account
+- Guidelines and best practices
+- Libraries and implementations
+"REST API"
+- OAuth scopes
+"API Methods"
+- apps
+  - oauth
+- accounts
+  - bookmarks
+  - favourites
+  - ...
+- statuses
+  - media
+  - ...
+- timelines
+  - conversations
+  - ...
+  - streaming
+- notifications
+  - push
+- search
+- instance
+  - trends
+  - directory
+  - custom_emoji
+- admin
+- proofs
+- oembed
+"API Entities"
+- Account
+- ...
+- Token
+```
+
+This was the majority of the work. Mastodon's REST API documentation was really messy, and it showed. Finding something generally entailed flipping back and forth between multiple pages and searching within them, and each page was very long.
+
+The first step was to promote methods and entities into their own sections. The "Entities" page was split into multiple pages, one per entity, and alphabetized. Tables were converted into headings, to allow for providing more information about each field.
+
+Methods were grouped by namespace rather than by feature-set, and with one level of nesting depending on whether the methods within pertained to accounts, statuses, timelines, notifications, etc. The pages for the Streaming and Web Push APIs were moved out of the overview section and into the methods section.
+
+Finally, a new section was created for a client development guide. The guide would cover the basics of REST API, how to make requests, how responses are structured, and authentication/authorization.
+
+## Technical writing
+
+### User guide
+
+With the information architecture phase done, writing the user guide was a straightforward task. Explanations of each feature and setting were added to the appropriate pages, as well as screenshots demonstrating proper usage. Tip boxes are included throughout in order to highlight important points.
+
+### Client development guide
+
+Writing this section taught me a lot about the basics of REST APIs, understanding HTTP requests and responses, providing parameters, and how OAuth works -- all information that I included in the client development guide.
+
+### Routes
+
+While documenting the REST API, I had to consult the Ruby on Rails routing config file extensively, so I took it as an opportunity to write a page about how routes work and how to read the routes file.
+
+### Specification compliance
+
+While the basics of ActivityPub federation were already written, the format of the old document simply pointed toward the server-to-server spec, as well as HTTP Signatures and Linked Data Signatures (with no real explanation beyond that). Therefore, I rewrote this page into multiple separate pages, each detailing the spec in question. The "ActivityPub" page now covered status federation and profile federation, the properties and types used in each, HTML payload sanitization, namespacing, and extensions (with sample payloads). "WebFinger" explained what, why, and how to use WebFinger for actor URI resolution. "Security" explained HTTP and LD signatures. "Microformats" explained the use of Microformats 2.0 and how they may be parsed, and "OAuth" covered the endpoints and flows implemented within Mastodon for obtaining a token.
+
+### REST API
+
+Methods now include the HTTP verb, endpoint, description, return type, OAuth scope, version history, request parameters, and sample response code and payload.
+
+Entities now include example payloads, as well as eacha ttribute and its description, type, and version history.
+
+## Outcomes
+
+> "Bless you for being here to work on the docs btw. It's a big relief."
+
+### Less missing information
+
+During the information architecture phase, a new skeleton was created as a proposed alternative structure. This process made the existing gaps in the old structure more obvious, and therefore those gaps could be filled during the technical writing phase.
+
+### Easier to make additions in an appropriate place
+
+Pages that were added after completion:
+
+- "Rate limits" was added under "REST API", describing how to deal with rate limits on requests made to the REST API.
+- "Bug bounties and responsible disclosure" was added under "Contributing to Mastodon", describing where serious issues should be reported if found.
+- "Running your own server" was added under "Using Mastodon", describing the reasons why a user might want to run their own server and linking to the "Running Mastodon" section. 
+
+The clear structure left in place by my information architecture work meant that it was almost immediately clear where to add these pages. 

content/work/pixelfed/index.md

@@ -0,0 +1,30 @@
+---
+title: "Pixelfed team member"
+summary: "Turning a one-person project into an organized effort."
+date: "2019-01-01"
+tags: ["pixelfed", "project management", "product management", "github issues", "documentation"]
+---
+
+## Overview
+
+## Being invited to the team
+
+I made that masterpost issue with every bug and missing feature from the initial beta release, with a big checklist and organized into areas of interest.
+
+dansup saw that and decided to invite me to join the pixelfed organization on github.
+
+## Responsibilities
+
+### Issue triage
+
+I implemented the current issue tagging system.
+
+Issues have tags by area, Milestone by rough version target, Project by which feature they pertain to
+
+### Design consultancy
+
+dansup does a lot of experimenting with building out mock features, and I'm there to tell him which ones are good ideas and which ones are bad ideas.
+
+### Release planning
+
+0.x betas each usually focus on one feature and related development around it. When the focus changes, a new 0.x beta will be tagged. We have a few more betas left, for circles, and for polish. If it weren't for me, dansup would have tagged 1.0 already and media attention would have been lackluster.

layouts/_default/single.html

@@ -7,6 +7,8 @@
 		<header class="section page-header">
 			<div class="container">
 				<h1 class="page-title">{{ .Title }}</h1>
+				<p class="page-summary">{{.Summary}}</p>
+				<img class="page-cover" src="cover.jpg">
 			</div>
 		</header>
 		<aside class="meta section">

resources/_gen/assets/scss/scss/main.scss_48b060fe05b0a273d182ef83c0605941.json

@@ -1 +1 @@
-{"Target":"scss/main.min.1728f3b8fb7e574269be9a411c55d3a93da926642f617fa9ec6871714626047e.css","MediaType":"text/css","Data":{"Integrity":"sha256-FyjzuPt+V0JpvppBHFXTqT2pJmQvYX+p7GhxcUYmBH4="}}
+{"Target":"scss/main.min.38ec2c33a877306d8370794aed7a2ff778484eed49da2c100f12c3180e387913.css","MediaType":"text/css","Data":{"Integrity":"sha256-OOwsM6h3MG2DcHlK7Xov93hITu1J2iwQDxLDGA44eRM="}}