Alexander Ryzhov
Apr 11, 2025

Keep documentation as close to the code as possible

If your code documentation is located on another site, e.g. external wiki, there is a chance that people won’t find it, or the external host might be down. The best documentation is docstrings within the source code.

And the interesting thing: It is a short edge between a comment and documentation.

Check this out:


func do_something() {
	// This is comment to do something
	...
}

// And this is documentation!
func do_something_useful() {
}

We want to keep documentation as close to the code as possible, so the best place for documentation… are comments! We don’t need a separate site for developer documentation at early stages - the separate site may only be viable for a big team, working across different projects, maybe in form of wiki.

The core of understanding is in the code: good developer reads the code first, and the comments/documentation just serve as pointing out why this solution is chosen. That’s the way of maximum efficiency.