but what I would do is add a comment in the code to specify the change and link to your documentation file for more details (if needed).

However, I have never seen any project doing it like that (for a good reason probably?).

I think what happens to me is that I completely lack discipline about structure and will often decide to re-organize things. So then I will tidy the documentation section which breaks links and nothing can be found. I would only be able to behave differently if I was very confident about what I will do and how I will do it from the outset; otherwise it is unavoidable part of learning and changing ideas through the life of a project.

One slightly more stable system I’ve had for my own code is to use the Issues tracker as a sort of documentation storage system. Open an Issue against the repo for everything I did, keep all notes in the Issue, and link to that by number like #1, which all the forges understand as special notation so it gets picked up in useful ways in terms of references.

I don’t do this too often because it’s a mess if anyone else ever wanted to utilize the Issue tracker and not what the Issues are for. Not to mention embarrassing. But I’ve resorted to it in situations where I had a huge amount of learning to do. With the idea that potentially could move the actual end project to a separate, cleaner repo once it was presentable, but I’ll cross that bridge when I get to it. I will say that despite being an abuse of the Issues tracker it has stood the test of time and I can go back to stuff I was working on years ago and find information stored in this way.

But with a regular fork that is made on the same platform as the original (eg forking a github repo to another github repo), you don’t actually get an Issues tracker; only the upstream can have Issues. So it’s a bit moot.

It’s probably not what you’re looking for but maybe this can give you any idea or see if this could fit your workflow?

Thanks for sharing. :) I hope you don’t mind me saying this but it’s nice to see commits like “Just a commit test”. I also have these as part of learning git.

I didn’t know we could use callouts like this in codeberg MD. Cool!

> [!CAUTION]  
> Sometimes...

Is there any specific reason to keep the docs in the wiki section? Vs markdown documents right in the wiki itself?

For my self I like to document in the code itself. It has one major benefit which is: I always know where the information is to be found. But there are some problems with it such as

• creates conflicts when merging changes from another repo or branch

• it makes the git history a lot messier because you have some commits on functional code and some on comments, all mixed up in a single document. I know with fancier git this could be tidier but I can’t reliably work at such a high skill level

• comments are not subject to syntax formatting so harder to read

• source document itself becomes too long to read and hard to understand

• extremely contextual to my skills and challenges at the time when I wrote the code; not what I will need to know in the future and not what others need to know

So not always the way to go.

thanks I was wondering about that but forgot to specifically ask :)

This is a case where both tools are invaluable.

The original find has much more comprehensive options. Of course it is extensively documented and you can find all kinds of information online about how it works and how to combine it with other tools to accomplish all kinds of tasks. And it’s GPL which is always preferable.

fd has a narrower range of functionality but goddamned it really is faster. fd can run several searches on the whole hard drive’s contents while find is struggling to get through just a single comparable search on the same set of files. For simple tasks, the cli usage for fd is less to remember and less to type.

If I had to choose, I’d stick with find because it can do everything, even if it’s slower and more cumbersome. But luckily, don’t have to choose, just have both and use them as appropriate.