Improve documentation

[gsambrotta]

I would suggest to:

• Add more code examples, particularly in the load-schema, context, form, map blocks. The map block is not clear that uses custom libraries.
• Add an intro or architecture section. A section where we explain how the flows work, what is a flow cloud, what is a flow builder, how they are represented in Angular, ... all this information to a higher level, not in detail.
• Collect some useful examples for JMESPath, as the official JMESPath documentation do not cover may cases

[gsambrotta]

• Add error handling to HTTP block
• Add "context" parameter to the Launch block: #424

[dahacouk]

@gsambrotta @lukestanley Putting Linear links (which are unfortunately private) into GitHub issues (which are public). I'm not sure it makes sense and anyone looking at these links won't be able to follow them and that will be frustrating.

[dahacouk]

@gsambrotta @lukestanley I'm not sure about adding an architecture section in the readthedocs. As I understand it, readthedocs is there to make it easier for developers to quick reference sections of code and/or functionality. We need to be careful because some of the architects (me) are not developers and neither are the end-users developers. Even though the end-users (mainly currently the collaborators) are currently not creating Flows themselves we want them to be in the near future. We need to think about how we have documentation for end-users too.

We also need to think about how we describe the architecture of the Kendraio App and where that resides and why. Is it the domain of the developers or the architects (some of which are developers and some of which are not developers (me)). When we describe the architecture do we want to get feedback from non-developers. Why are we describing the architecture in readthedocs? Does it help to make coding faster? Thanks for raising this.

[gsambrotta]

@dahacouk Good points. Agree with the linear link and I will remove it. I was being a bit selfish and I added to simplify my life as I thought I will work on this issue, but we never know what the future brings, so better to keep everything clean.

Maybe I misused the word Architecture. What I meant is to simply have a section where we explained every section of the Kendraio App and how they are related to each other. What is a Flow Cloud, Flow Builder, Query Builder, the login... And yes, also a more technical page where we explained how the UI is correlated to the code. Where do I find the Block? Where Can I modify the login page? What about the tests? This is extremely helpful for new developers that want to contribute. It helps to:

• Welcoming and supporting new devs (attracts more devs to help out on the project)
• Code faster
• Code more confidently
• Create fewer bugs
• Feeling less lost and frustrated If devs feel there is a lack of documentation, they will pick another open-source projects. There are so many choices out there, why get frustrated when you are coding for fun, for a purpose and for free?

[dahacouk]

That’s really help @gsambrotta . I understand where your motivation is coming from and that really helps me. Over the coming weeks I will be doing more investigation into the relationship between coding and Flow-ing. There's always a balance between where we should invest Kendraio time and why. But I need to understand more about why things should be written in Readthedocs rather than Google Docs, and what the implications of do so are. Cheers! cc @lukestanley