top of page

My Portfolio / DocumentationStyle Guide

Personal project: information development and style guide

Aim: Create a proof-of-concept website summarising my knowledge of technical writing and UX writing best practices and guidance. 

Problem

 

In 2022, I wanted to collate my knowledge of information development, technical and UX writing best practices, and the docs-as-code approach. After discussing it with a friend, I sought to create my own online documentation using the same tools that you would use to code. This would ideally show the efficacy of modern documentation practices (in this case, docs-as-code) whilst also allowing me to disseminate my knowledge and showcase my skills in information development.

At first, it didn't matter to me what I created my own online documentation about, but since I was also looking to collate my knowledge of technical and UX writing best practices, I thought it would be fun to combine these two objectives. I also liked that this plan was a little meta: I liked the idea of having online documentation about online documentation.

Process

1

Brainstorm

2

3

4

5

Build

Write

Publish

Maintain

1. Brainstorm

I worked with a friend (a UI engineer) to investigate tools for creating online documentation. I was already working as a technical writer using a docs-as-code framework for a software company and he had an interest in the docs-as-code approach. He helped me choose and set up the tools for implementing version-controlled, online documentation.

2. Build

I wanted to use common tools as well as tools I was already familiar with, so we decided to create and manage content in Markdown files that I edited in VSCode and, using Git for version control, stored in a remote repo in GitHub. We added extensions to VSCode for spelling and Markdown validation. We used Docsify to generate documentation from those Markdown files and GitHub Pages to publish this content to a public website. You can read about the process in the documentation itself: Example use case.

3. Write

With the tools and framework in place, I started drafting content in Markdown files using VSCode, drawing on my knowledge and experience of information development. I decided to write in my own style, leaning more towards (but not dictated by) industry standards for technical writing. Initially, I was only intending to document style guidance for my own reference and then, because I learn by writing things down and organising information, the docs-as-code process we were adopting. This spiralled into a broader resource for information development.

Screenshot 2024-05-04 at 17.07.04.png

4. Publish

After writing and editing the content in Markdown files using VSCode, I pushed this content to a remote repo on GitHub, using Git for version control. Later pages in the online documentation covered more technical content that I ran by my friend for accuracy and sense. I did this using Pull Requests in GitHub, where he could review my edits before we merged the content for publication. We set up GitHub to automatically publish merged content to my GitHub Pages website: https://jeunese.github.io/#/.

5. Maintain

After writing and publishing the content, I left the website to work on other projects. In 2024, I decided I wanted to update the website, which involved re-establishing the tools I had set up on my new computer. To see what I could remember, I attempted to do this without the help of my friend and then began updating and re-writing content.

Outcomes

 

This was a proof-of-concept, personal project that resulted in a public website on GitHub Pages: https://jeunese.github.io/#/. It was never intended to be a polished, all-encompassing reference. Since my friend and I were the only intended audience, I wasn't concerned with whether the website had a vanity URL or looked professional. I simply wanted to see if I could do it.

I have since used and shared my online documentation for its style guidance and technical writing concepts.

Screenshot 2024-05-04 at 17.43.20.png

Challenges and learnings

 

I don't have a technical background and relied on my friend to help me set up Git, a remote repo in GitHub, Docsify, and GitHub Pages. When attempting to rstart contributing to the information development guide again in 2024, I encountered a number of challenges that I attempted to fix by myself based on trial-and-error and Googling:

  1. SSH authentication issues. I switched to HTTPS as an alternative authentication method and then encountered difficulties with cloning the repo in VSCode and pushing changes, possibly due to incorrect credentials.

  2. I received various error messages related to repository paths and file operations in the VSCode output, indicating potential issues with repository configuration or file paths. At one point, I had issues with .gitmodule files and submodule configuration.

  3. Issues related to the .DS_Store file. This was already in the gitignore configuration but still resulted in warnings about uncommitted changes and merge conflicts.

bottom of page