I’m Struggling With Writing Project Documentation How Should I Start?

[jessebardon]

I’ve been learning Swift and working on my own projects, but I’m realizing that writing clear documentation and project explanations can be just as challenging as coding itself. Sometimes I get stuck on how to explain my thought process, structure my code explanations, or make examples understandable.

I’ve seen examples on 5staressay that show different ways to organize writing and explain ideas. It’s not about copying, but seeing how things can be structured helps me plan my own documentation and communicate my projects more clearly. I’d love to hear how other developers handle writing about their projects or documenting code effectively.

[Joseph_Heck]

Hi Jesse,

Welcome to the Swift community!

You've got a great, although super broad question - let me share a little bit of how I approach these efforts, and I'm happy to provide more details if you're interested.

At the heart, there's a couple of questions I try to have pinned down (that's not always possible, but I try):

• who's the audience reading the docs - what do they know, what context do they have about what you're writing, and ideally what are after or trying to do with the content you're creating?
• Aligned closely with the above, what's the content you're creating trying to achieve?

There's various formalisms for the second here, but the general patterns are:

• tutorials
• how-to guides
• conceptual explanations
• reference

the four of these are labels put into the corners of a grid that line up with "trying to learn <----> trying to use" in one direction, and sort of the immediacy of the need "want to use the knowledge down the road" <----> "I need to solve a problem right now, how do I do this thing?"

Then there's some common goals that lean into based on where this all falls out.

Tutorials, for example, I try to line up a good, real example (surprisingly difficult) that's also simple enough. I aim for a single, clear path to follow (not diverging paths or alternatives) for a single narrative flow. Ideally it builds on pieces as it goes, and creates an easy to follow progression that both shows how to get something done, and touches on places where it explains as it's needed or most useful. I'll put variations or side paths in asides, but I try to almost ruthlessly prune those to keep things simple.

For how-to guides, I tend to start with a problem that's being solved, note down the moving parts that a developer needs to be aware of to achieve it, and pick a step-by-step path that lets me introduce concepts (if needed) in small chunks while working through the progression of the task being achieved. In my case, these are often short(er) articles, and the outline of the section headings reads like a "here are the steps to do this thing", with the detail inside the sections.

For me personally, the hardest part is teasing apart my own mental model, which is rarely as orderly as all this. I spend a bunch of time (when I'm trying to write) working through examples and verifying that what I think is correct actually is - and in some cases that's really hard. There's workarounds, optional side paths, choices in multiple ways to solve a problem, etc - all of which I try to nail down into something slightly more cohesive. I very frequently have to write a draft and then leave it alone and switch topics to something else for a day or two to get some distance between "what I know I said" and "what I actually wrote". It's incredibly difficult to spot what you missed, but intended to write, when it's super fresh in your head.

While I've written and published books in the past, I personally think there's a more value in shorter, focused content that doesn't take as long to assemble and publish. When I was publishing books (both through published and self-published), my general expectation was that anything I wrote was most useful for 3-6 months, generally useful for a year, and anything beyond 18 months was just good luck. That's all due to the rate of change in technologies.

When I'm tackling something like "documentation for a library", I have a mental checklist that I try to use:

• introduce the library and what it's helping you do
• make sure there's a quick path to getting it installed
• make sure there's a simple possible example of how it helps you do whatever it enables
• make sure there's clear reference API for the options that it has, and that all the public API has some description around it, especially functions/methods (since that's where most of the usage happens)
• organize the reference API so that the most common things are listed first, and organize any long lists of types or methods into smaller groupings that are easy to skim to find what you're trying to achieve.

Examples, frankly, are the hardest but most critical. I've run into some lovely API design that was just entirely opaque to my brain - I just didn't get it - until I saw an example of it being used, and then it clicked. So if when I'm doing project work like this, I try to iterate a LOT on the examples, and get as many established if there's multiple things that can be done. The more the better. These days, almost doubly so with the rise of agentic systems using the documentation and providing better results when the docs themselves have clear good practices and examples included within.

So that's a broad swath and brain dump. Let me know where I could help more, or what you're trying to work on and stumped with, if there's something more specific. You're welcome to reach out directly (DM me on these forums) if you'd like - I'm more than happy to help share what I've learned or share more specific pieces if it'd help.

[Slava_Pestov]

@jessebardon

I’d love to hear how other developers handle writing about their projects or documenting code effectively.

I agree with everything @Joseph_Heck said, and wanted to add a few thoughts of my own.

I'm still an amateur when it comes to technical writing, but here is some general advice I've figured out over the years. Keep in mind that this is mostly from writing programming language and compiler-adjacent documentation, so much of it may not apply to your situation, but I hope it helps anyway!

• Writing is a distinct skill from coding, so even if you're an expert coder, it takes a lot of practice to write well. Think of the first large program you ever developed. It may not have been the most readable, maintainable, or performant code. Writing is like that too. That's okay!
• Just as it often takes some refactoring or even rewriting from scratch before a piece of code looks right, don't be afraid to redo parts of your docs. It's hard to get it right on the first attempt.
• However, starting with an outline or some kind of general structure that you can fill in gradually is better than staring at a blank page, even if you end up completely "refactoring" this structure later.
• Just like we rarely write a program from the first line to the last, you don't have to write prose in the order it will be read. If you get writer's block, skip ahead and try to fill in something else.
• The structure of documentation will rarely match the structure of the code. You can use the organization of the code as a starting point, but after you start writing you might end up completely re-organizing everything.
• Often, “iterative deepening” and re-visiting topics in more and more detail works much better than a document that lists all widgets of Foo type, followed by an exhaustive enumeration of the next unrelated topic, etc.
• Use consistent terminology, and define all terms before they're used. For a particularly tricky piece of writing, you might want to add a glossary of terms at the beginning or end, but often this is not really necessary.
• At the same time, avoid cluttering the reader's head with unnecessary terminology. If a term is only needed once or twice, it might be better to just explain what you mean in the handful of places where it comes up, instead of formally defining it first.
• Relationships between concepts are just as important to define as the concepts themselves.
• Some redundancy and re-explanation between the different sections can be good in longer documents, to re-orient the reader, who will not always be reading everything from start to finish.
• Avoid phrases like "simply", "just", "trivially", and so on. These can be off-putting to a confused reader who might not find something quite as simple as you think, and they can hide assumptions. Just remove the word entirely, or actually explain why something trivially follows, etc.
• Setting a document aside for a while and coming back to it later can help. You'll naturally forget some of what you wrote, and deficiencies will make themselves more apparent as a result.
• Examples are really critical, but a clear "mental model" that explains the key concepts in their own terms is important too. This doesn't have to stand alone without the examples, but it should complement them. Usually you want to start with an example to give the reader an "aha" moment first, so that they then read the abstract explanation to fill in any gaps in understanding, before everything "clicks" into place.
• For the most detailed "specification" sort of document, approach the definitions and examples like playing a game. You're the adversary, trying to derive some kind of contradiction or nonsense consequence from the text. Try to break the formalism, then add more detail to close the hole, and repeat until it's airtight.
• When proofreading, I find it much easier to catch mistakes if I print the document on paper, or even read it on a different screen than the one I wrote it on (tablet/phone/laptop, etc). I'm not sure why, but it really helps!
• Also, for longer documents, I find that reading them backwards can also surface mistakes, out of order content, and so on, that I may have missed on first reading.

Also, I think your post is mis-categorized. Right now it's in the "Hummingbird" category, but it has nothing to do with that web framework as far as I can see.