Basically all documentation tools I’m aware of are aimed at communicating things others. Is anyone aware of tools that are instead focused on personal documentation? Tools that are tied into the source/source control in some way, but that are for personal use and not shared with others? Obviously people can make their own little conventions and things in stuff like org mode. But I’m curious if anyone is aware of purpose built tools for this.

I guess my experience is that communicating with my future self is a lot like communicating with other people.

Interesting question, @Jimmy Miller. Could you detail what type of documentation do you have in mind? Is it documentation of code, or something else?

https://roamresearch.com/ is the hip startup in this area

@Tudor Girba There are all sorts of personal notes I'd love to leave in code bases that either 1) I don't want anyone to read because the are opinions 2) aren't fully formed yet so shouldn't be shared widely. More often than not it would be documentation of context and ideas than what the code itself does. Or reminders to myself why I can't do certain things I want to do. But I think where these notes would be particularly useful is when trying to learn a codebase and a system. How do all these things hook together? What things have I discovered so far and what open questions do I have? What pitfalls have I run into? In clojure I would also leave some "Rich comments" of code that I can run in the repl but isn't cleaned up for others. If I could make these personal notes I would write more documentation. Because now documentation doesn't have to be clean all at once or something that will pass code review. I can continue to refine overtime and promote.

@Jimmy Miller how would connect the notes to the code? one solution I can think of: • create a Tiddlywiki instance only you can access • write your thoughts on a piece of code in a tiddler (Tiddlywiki name for entry or note) • link to the tiddler in a comment near your relevant piece of code

I find hyperlinks into codebases incredibly useful. Thank you GitHub and https://plugins.jetbrains.com/plugin/8183-gitlink! With hyperlinks for any line of code at any point in time I can just use regular docs (Google docs, LaTeX, Confluence, Markdown, plain text) to create pretty decent private documentation. I still can't hyperlink to any line of code at all points in time, so that it's the same line but carrying forward transparently as new commits roll in. But I find it's actually better to err on the side of situating documentation timefully rather than timelessly. That way I'm constantly reminded that documentation can go out of date. In principle it sucks that I can't get backlinks. "What are all my notes that link inside function

foo

?" But in practice I've just never had that many docs about any single function, so I haven't missed it that much. Plain docs + hyperlinks may well be the 80% solution that gets us well into the region of diminishing returns.

The Software Heritage archive has the same functionality for any archived repository (all of GitHub, but also much more). Here is an example that I recently sent to someone.

I think this is where structure editors and environments like Stamper could really shine: https://mobile.twitter.com/supercgeek/status/1230163240815955968

One feature I always add to the text editors I'm using is being able to highlight text, and then hit a keyboard shortcut to create a Markdown link to that source code on the source control site's web interface (e.g., usually GitHub). It uses the permanent URLs, so that the links are evergreen. Here's what one of these links looks like:

[`SodaPop/Constants.swift`](<https://github.com/repla-app/SodaPop/blob/107b78ed130fe0e974f8569d1dc7fbdaed1f1e3b/SodaPop/Constants.swift#L9-L13>):

	public let pluginNameKey = kPluginNameKey
	
	let defaultNewPluginIdentifierKey = kDefaultNewPluginIdentifierKey
	let pluginFileExtension = "replaplugin"
	let duplicatePluginsWithCounterMax = kDuplicatePluginsWithCounterMax

@yoshiki Thanks for this reference, the user interface of Stamper looks very interesting for exploratory work, which is something I am particularly interested in. Now what I'd really like to have is "Meta-Stamper": the user interface in a form that I could adapt to use something else than p5.js, for explorations in domains different from graphics.