Ask HN: How Do You Approach Public Docs for Small Open-Source Projects?

2 pointsjeeybee10mo ago1 comments

Hi HN,

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

1 comments

gus_massa10mo ago

"When everything fails, read the manual." --Anonymous?

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.

j / k navigate · click thread line to collapse