Documentation Reorganization

[avaidyanatha]

Main Inspiration

The documentation experience doesn't progress naturally and the "Tutorials" section is currently a catch-all for lots of different types of content. There's a lot that can be improved with the structure, so this is a first pass at that.

Main Changes

• More organization around Tutorials, moved all contribution guides/tutorials to Contribution
• Created a Reference category to capture architecture/API docs
• Created a Project Overview category to capture roadmap/changelog/careers
• Renamed and split up the getting started guide to be clear in the steps and milestones being achieved

Misc Changes

• Small grammar/spelling changes here and there
• Updates to article titles for clarity

Notes/Self-Feedback

• In this version, the contribution tutorials are buried pretty deep and could be missed pretty easily, this might be fixed by moving them back to Tutorials under a "Contribution" subcategory

[avaidyanatha]

Preview the changes here: https://docs.airbyte.io/v/abhi%2Frestructuring/

[michel-tricot]

This is great!

[michel-tricot]

Agree with your point about the contribution tutorials

[davinchia]

Nice one @avaidyanatha! I like the breaking out into Quickstart, Tutorials and Example Use Cases. I added a change that stop us from auto-generating some docs and should help the build pass.

From me:

• Can we change the Reference term? I usually associate references with specification-style documentation more focused on listing out the class + methods instead of what we have which is more along guides/conceptual docs explaining what is happening. What about a catch-all like 'Understanding Airbyte'? What do you think?
• Project Overview seems strange to me as we already have an Introduction section, especially since it's at the bottom of our left nav bar. What about just breaking all those sections out into the top level nav bar? Would the nav bar be too cluttered?

Non-blocking since this is strictly better than our current state.

One question before I approve - how were the changes made? Was it by Gitbook? Asking since we had Gitbook do some weird formatting stuff in the past. If it is I'll give this a closer look over before approving just in case something funky happened.

[avaidyanatha]

Nice one @avaidyanatha! I like the breaking out into Quickstart, Tutorials and Example Use Cases. I added a change that stop us from auto-generating some docs and should help the build pass.

Thank you @davinchia, really appreciate it! Also... thank you so much for fixing the autogenerated docs, was wondering why the build failed.

• Can we change the Reference term? I usually associate references with specification-style documentation more focused on listing out the class + methods instead of what we have which is more along guides/conceptual docs explaining what is happening. What about a catch-all like 'Understanding Airbyte'? What do you think?

I can get on board with that for the Architecture section, as that fits really nicely under a "Understanding Airbyte" or "Concepts" section. For the API docs though, those are more strictly reference from my understanding.

• Project Overview seems strange to me as we already have an Introduction section, especially since it's at the bottom of our left nav bar. What about just breaking all those sections out into the top level nav bar? Would the nav bar be too cluttered?

We link to a lot of these pages directly (Roadmap, Changelog, Careers) from the website, GH repo, and introduction section, which is why I wanted to declutter by keeping them in their own section. Maybe it needs a different name?

One question before I approve - how were the changes made? Was it by Gitbook? Asking since we had Gitbook do some weird formatting stuff in the past. If it is I'll give this a closer look over before approving just in case something funky happened.

I made all the changes manually in my IDE, so as far as I know, we shouldn't have any issues with that!

[davinchia]

@avaidyanatha happy to help!

I can get on board with that for the Architecture section, as that fits really nicely under a "Understanding Airbyte" or "Concepts" section. For the API docs though, those are more strictly reference from my understanding.

What about puttling the API references to the top level as a standalone page for now and bringing all the remaining documents up one level and renaming the section to 'Understanding Airbyte'.

We link to a lot of these pages directly (Roadmap, Changelog, Careers) from the website, GH repo, and i ntroduction section, which is why I wanted to declutter by keeping them in their own section. Maybe it needs a different name?

Hmm good point. What about getting rid of license/changelog/roadmap and promoting the career page to the top level? Willing to bet money most people actually scroll through all of the introduction as it's pretty short and will have seen those sections/know where to find the info. Putting careers up also helps with people interested with working with us.

Cool. Manual edits should be great. Approving for now, please consider my comments as food for thought rather than required changes.

[jrhizor]

Why is this removed instead of just changing the target, which would fix the build?

[jrhizor]

I just changed the path instead. Now it should still auto-update docs instead of keeping a stale copy.

[avaidyanatha]

@davinchia

What about puttling the API references to the top level as a standalone page for now and bringing all the remaining documents up one level and renaming the section to 'Understanding Airbyte'.

Solid idea, done.

Hmm good point. What about getting rid of license/changelog/roadmap and promoting the career page to the top level? Willing to bet money most people actually scroll through all of the introduction as it's pretty short and will have seen those sections/know where to find the info. Putting careers up also helps with people interested with working with us.

I left Project Overview in for now (we can think of a better name later) and moved Careers up to the top level for visibility.