Improving (Perceived) Complexity

[saintstack (Michael Stack)]

@panghy

…

• A group of volunteers would have to decide on the audience, structure, objective of the first pass of documentation with some idea of who should do what and what’s the point when we would merge to main (i.e. who’s signing off the whole thing or is this a “good enough, merge as we go thing” – I don’t think for a seriously complicated project like FoundationDB we can to do that honestly)
  …

I’d suggest such an undertaking needs a leader/organizer. Success will be more likely if they know FDB and are skilled writing and organizing documentation.

S

[dlambrig (Dan Lambright)]

As a small step towards improving FDB’s community health, we have created a FoundationDB discord channel. Please use the invitation link below to join- the link will expire in 7 days. I expect the room will be relatively quiet in the near term until awareness grows. Perhaps the channel could be used for discussions about documentation.

If all goes well we will post an announcement about this channel to the forum and update the documentation to link to it.

Dan

Join the FoundationDB Discord Server!

[Semisol]

@panghy

A group of volunteers would have to decide on the audience, structure, objective of the first pass of documentation with some idea of who should do what and what’s the point when we would merge to main (i.e. who’s signing off the whole thing or is this a “good enough, merge as we go thing” – I don’t think for a seriously complicated project like FoundationDB we can to do that honestly)

I think that the “version 1” documentation should be target:

• Potential users to be able to understand the benefits of FDB easily (we don’t have anything close to how companies like CockroachDB market their product)
• Layer developers to be able to know the core concepts of FDB, what to do and don’t, and some example “recipes” to handle design patterns like long-running transactions and large values/transactions
• Database administrators to be able to deploy a FDB cluster, configure it according to their needs, monitor core metrics and diagnose the most common issues.
  • I think here matters a lot, and where current docs lack the most information.
• Certain FDB tuning and optimization details.
  • I’m currently just writing whatever comes to mind here locally, to contribute it in the future.
• An overview of most features that the community may be interested in, their status, and how to use them. Many features like tenants and rangeconfig are not documented.

It cannot cover everything, but someone should be able to manage a small sized cluster based on the documentation.

The docs should focus more on getting people started easily but with minimal compromises, so that they eventually scale out from a small project, or transfer their positive experience with FDB to larger deployments.

[panghy (Clement Pang)]

Well just to circle back on this thread, we finally have https://foundationdb.vercel.app as a first cut of this. Most of the discussion is now on discord (esp. #documentation) but at least something came out of this (it took a while of course…)