Guides are Hard

2025-01-09

My recent log entry about NNCP file requests has renewed my motivation. Soon after posting it, I began rewriting my NNCP guide to include every feature and option the software has to offer. There are some important and useful aspects of NNCP that I left out of my previous guide, and I want to address that.

The new guide will be split into multiple pages and sub-pages, so I needed a plan. What information would go into which page? NNCP's configuration is dense: how finely should I split it out? Does information about routing go into the page for transfer commands, or does it go into the page about configuration--or both? Should I explain concepts that external to NNCP but appear in its configuration, like multicasting or Yggdrasil? To what extent should I include my own tips and tricks?

I put together a rough outline and began writing pages based on it. But after writing about half a dozen, I realized that I still couldn't figure out where I wanted specific information to go. Writing guides is hard; writing them comprehensively and in a way that makes sense is even harder.

I often struggle with articulating my thoughts in a coherent way. I clearly know and understand what I want to say, because I can perform tasks based on my knowledge and make sound decisions based on my understanding. But as soon as I try to put that knowledge into words, I flounder. Everything I wrote becomes an opaque mess, reading more like a stream-of-consciousness than a well-organized technical document.

I need to practice my skills at outlining and organizing information. Maybe then I'll be able to write something more useful than the long, rambling NNCP guide I have now.

=> Up One Level | Home

[Last updated: 2025-01-13]