Skip to content
DevPortals.Tech
Docs Portfolio
Blog

workflow

4 posts with the tag “workflow”

From Chaos to Clarity: A Technical Writer's Journey Through Git Cherry-Picking and Team Collaboration

- 9 min read
Joaquin Romo

Introduction

Section titled “Introduction”

As a Senior Technical Writer, my role extends beyond crafting clear documentation—it involves navigating complex technical challenges to help my team achieve our objectives. Recently, I led an effort to salvage months of work from a stale feature branch, teaching me valuable lessons about git workflows, team collaboration, AI-assisted development, and the resilience required in technical documentation work.

The Challenge

Section titled “The Challenge”

Our team had been working on a major documentation revamp for several months. Multiple writers contributed to a shared feature branch, building a comprehensive update to our product’s documentation. However, as weeks turned into months, our feature branch became increasingly disconnected from the main branch—912 commits behind, to be exact.

The branch had contributions from numerous team members, each adding valuable content, but the cumulative drift from main created an untenable situation. When we finally attempted to merge, we faced hundreds of merge conflicts. The traditional merge approach would require untangling conflicts across dozens of files, risking the loss of carefully crafted content or introducing errors that could take days to identify.

We needed a different strategy: cherry-picking.

From Forks to Branches: Streamlining Team Git Workflows

- 4 min read
Joaquin Romo

As part of a GitHub working group within a 50-person technical writing team, I recently helped lead our transition from a fork-based workflow to a centralized branching strategy. This shift simplified our collaboration model and reduced friction across four sub-teams. Here’s what we learned.

The Challenge

Section titled “The Challenge”

Our team of technical writers was using personal forks of our main documentation repository. While this approach worked, we identified several pain points:

  • Extra complexity for common operations
  • Confusion about which remote to push/pull from
  • Inconsistent workflows across team members
  • Limited value for our use case compared to open-source projects

The GitHub working group formed with representatives from each sub-team to evaluate whether forks still made sense for our internal collaboration model.

How I'm Using MDX Frontmatter to Scale devportals.tech

- 4 min read
Joaquin Romo

Building devportals.tech has been an exercise in practicing what I preach about documentation engineering. One of the most impactful decisions I made early was leveraging MDX frontmatter not just for basic metadata, but as the foundation for scalable content workflows. Here’s how it’s working in practice.

Starting Simple, Scaling Smart

Section titled “Starting Simple, Scaling Smart”

When I first set up this Astro Starlight site, I could have just used basic Markdown. But knowing I wanted to build something that demonstrates professional documentation practices, I started with structured frontmatter from day one:

---
title: "Content Branching Strategy for Documentation Teams"
description: "How to manage documentation releases, staging, and quality control using Git workflows"
date: 2025-09-23
authors:
  - name: Joaquin Romo
tags:
  - git-workflow
  - content-management
  - documentation-strategy
  - staging
---

Simple, but it’s already paying dividends.

Content Branching Strategy for Documentation Sites

- 3 min read
Joaquin Romo

When building a professional documentation site like DevPortals.tech, maintaining content quality while enabling rapid development requires a strategic approach to version control. Here’s the branching strategy I’ve implemented for managing documentation content lifecycle.

The Challenge

Section titled “The Challenge”

Building a portfolio-quality documentation site presents unique challenges:

  • Quality vs. Speed: You want to publish frequently but maintain professional standards
  • Work-in-Progress Content: Some sections need extensive research and iteration
  • Professional Presentation: Your live site represents your expertise to potential employers
  • Development Flexibility: You need space to experiment without affecting production