Ask HN: How Do You Approach Public Docs for Small Open-Source Projects?
I’m the maintainer of PGQueuer, a minimalist job queue for Python that runs entirely on PostgreSQL—no Redis, brokers, or additional infrastructure required. It’s designed to offer solid concurrency with low overhead and fit seamlessly into projects that already use Postgres.
I’ve been working on improving the public documentation [1], and I’m looking for feedback from others who’ve gone through this process—especially those maintaining small, technical open-source projects where all the important knowledge lives in the docs. There’s no internal documentation and likely never will be, so clarity and accessibility are essential.
I’d especially appreciate your thoughts on:
* How do you decide what’s worth documenting for a technical audience who might just read the source anyway?
* How do you balance being thorough without overwhelming the reader?
* I’m currently using Read the Docs [2], but I’m considering switching to a self-hosted MkDocs site. What have your tradeoffs been between Read the Docs and self-hosting?
* What practices have helped you keep your docs in sync with your codebase?
* What’s worked well (or poorly) for encouraging contributions and getting users to help improve the docs?
If you have time to browse the current docs [1], I’d love to hear what’s missing, what’s confusing, or what stands out as helpful.
I’m here to learn from your experience—tools, workflows, hosting decisions, contributor strategies, anything. Thanks in advance!
---
[1] https://pgqueuer.readthedocs.io/en/latest
[2] https://readthedocs.org/
[3] https://github.com/janbjorge/pgqueuer