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
gus_massa•6mo ago
Add a few examples! I wish every new programming language posted here has an example section, like Hello Word and Fibonacci and 99 Bottles of Beer. Your project is not a programming language, so the examples should be different. But remember to add a few examples.
---
> for a technical audience who might just read the source anyway
"When everything fails again, read the source. -- Me, now
Many users will use your library without understanding the implementation details. It's a feature of a good library, so more people can use it.
And there are sometimes subtle details, like in "f(x, y)", can x and y be equal or y must be always greater than x. Perhaps it's easy to discover reading the source or perhaps the check is hidden after a few subroutine calls. Perhaps when x and y are equal f does nothing, and some libraries decide to check that and skip the situation and other to raise an error and other to make a huge mess.