Add content from design docs to datafusion site

[matthewmturner]

Is your feature request related to a problem or challenge? Please describe what you are trying to do.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
(This section helps Arrow developers understand the context and why for this feature, in addition to the what)

I think it would be really helpful to new / existing contributors and users if we incorporated the implemented design docs into the official datafusion site. This could probably be done as part of #1821 which i hope to work on in the coming weeks but I wanted to raise separately to discuss (if needed) / collect the documents.

Right now the design docs ive book marked are the following:

https://docs.google.com/document/d/1Z1GO2A3bo7M_N26w_5t-9h3AhIPC2Huoh0j8jgwFETk/edit#heading=h.dpji9hy5exqs
https://docs.google.com/document/d/1BT5HH-2sKq-Jxo51PNE6l9NNd_F-FyyYcyC3SKTnkIA/edit#heading=h.ims7dd49jei1
https://docs.google.com/document/u/0/d/1Bd4-PLLH-pHj0BquMDsJ6cVr_awnxTuvwNJuWsTHxAQ/mobilebasic#
https://docs.google.com/document/d/1ZEZqvdohrot0ewtTNeaBtqczOIJ1Q0OnX9PqMMxpOF8/edit#heading=h.358nvuimx7yr

Describe the solution you'd like
A clear and concise description of what you want to happen.

I dont have a strong opinion yet on where these would fall in the site and the docs will likely need some cleaning up in advance but i would like to better expose this great source of information.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

[matthewmturner]

@alamb @yjshen @houqp @rdettai @Dandandan @yahoNanJing @gaojun2048

If any of you know of other design documents (or know someone else who does) can you please link them here?

[jackwener]

It's great! I read these doc and they is useful to me. I believe that it's a useful information to the new contributor.

There are two options.

• put it to the repo subdir
• put it to the website

cockroach db use the first method

I consider the first it may be better, because design doc/meeting record is more developer oriented.

cc @alamb @houqp @Dandandan @yjshen , how do you think about this.

[matthewmturner]

its a fair point.

i know @xudong963 has spearheaded getting an RFC setup in place for datafusion. however, at this time a majority of the docs live in this more informal google doc setup.

personally, i dont think they need to be mutually exclusive. i think the site can have user guides, tutorials, cookbooks, and design docs (i use the official arrow site as reference) but we can still use RFC thats memorialized in repo as well and only once finalized it can be added to site.

i think in general my idea is just to expose this information and given i plan on doing a datafusion site / docs focus after completing current priorities i thought i would handle this as part of that.

[jackwener]

Make sense❤.

[yjshen]

I agree the design docs are of great value for every developer; it helps us to get outlines quickly.

My only concern is the potential confusion when docs and actual implementations are out of sync. For example, the memory management doc I drafted previously is quite different from the current code. I gradually implement it, gather comments, and adapts according to reviews. The gap is growing through many follow-up PRs with new ideas or needs.

I'm not aware of good practices of constantly syncing design docs and code. It might be challenging. But if someone has excellent thoughts or best practices on this, I'm willing to follow instructions and always keep docs updated to date from my side. It would ideally reflect the evolutionary flow of our practices and the driving reasons behind them.

Thanks again for the efforts to make our community more developer-friendly.

[matthewmturner]

@yjshen great point. what comes to mind as an option to help with the ongoing maintenance burden is adding inline comments (not doc comments) to the relevant sections of code that link to the attendant design doc. This way if material changes are made at least it should be visible to the person making changes and whoever is reviewing which should hopefully be good reminder to sync up the design doc.

[alamb]

I have never worked on a project where the design docs and code did not drift out of sync over time. I think it is inevitable.

The code always ends up being the final reference. I think best practice is:

1. Strive to document the code itself as much as possible (including examples)
2. Document key points / design criteria or rationale (that might not be obvious from code or tests) in extended docstrings as well

[alamb]

FWIW adding links to old design docs is reasonable as future readers may find value in seeing the thought process and evolution that has occured. But I think the effort to keep the design docs up to date is unlikely to be expended

[alamb]

I will work on this over the next few weeks

[alamb]

I think we have incorporated most/all of the content from older design documents that might still be relevant . I don't think this issue is very actionable anymore so I am closing it. Please let me know if you disagree or of there are particular docs that should be ported