Next steps to improve Interledger's technical side learning curve

Hi guys,

I had previously sent this email to Adrian and David just to bounce these thoughts off them, now I’ve written a revised version after the Community Call we just had today, just to share the topic with everyone interested:

This last month I’ve been learning about the Interledger protocol, its specifications and I’ve also gone through the codebase of the Java and JavaScript implementations. Over this exercise I’ve come up with a few structural issues I want to share with you and that we may want to improve upon if we aim to make Interledger more accessible to future contributors. I sense that the learning curve for a new engineer trying to get up to speed with Interledger is very steep; I shared my concerns about this with some of you and we were in agreement, so I will outline these thoughts for all of you:


-        Lack of technical documentation: whereas the high-level explanations in the RFCs are highly detailed and appropriate, the technical documentation is almost non-existent. Having simple diagrams of the inner structure of each project along with a listing of both internal and external libraries and dependencies would make the codebase much more understandable and accessible. The creation of detailed documentation might not be feasible if there are significant changes to the codebase in a regular basis, but I’m sure that a simple and concise documentation structure would be easily maintainable.


-        Follow-the-flow example: I think that in complex software architectures the fastest way to get acquainted with the codebase is to follow a real working example; in Interledger’s case it would be following the flow of a payment from beginning to end (with breakpoints on every class and/or detailed logging). I don’t know if this can be easily explained/documented but, having witnessed a few demos already, even if parts of the flows were hardcoded it would still be instructive.

These are just my observations from a month’s worth of studying, I highly encourage anyone with ideas or content related to this topic to also share. I hope we can all work to address these learning difficulties that any new joiner will face, especially if we want new contributors who don’t have this project as their full-time job; right now having to “reverse-engineer” everything on the codebase to really understand it would be too time consuming, and it’s only going to get harder as it grows more complex. If we make the learning curve shorter I’m sure we’ll also make faster progress with the various ILP projects.

Kind regards,
Juan Carlos

________________________________

AVISO DE CONFIDENCIALIDAD.
Este correo y la información contenida o adjunta al mismo es privada y confidencial y va dirigida exclusivamente a su destinatario. everis informa a quien pueda haber recibido este correo por error que contiene información confidencial cuyo uso, copia, reproducción o distribución está expresamente prohibida. Si no es Vd. el destinatario del mismo y recibe este correo por error, le rogamos lo ponga en conocimiento del emisor y proceda a su eliminación sin copiarlo, imprimirlo o utilizarlo de ningún modo.

CONFIDENTIALITY WARNING.
This message and the information contained in or attached to it are private and confidential and intended exclusively for the addressee. everis informs to whom it may receive it in error that it contains privileged information and its use, copy, reproduction or distribution is prohibited. If you are not an intended recipient of this E-mail, please notify the sender, delete it and do not read, act upon, print, disclose, copy, retain or redistribute any portion of this E-mail.

________________________________

CONFIDENTIALITY WARNING.
This message and the information contained in or attached to it are private and confidential and intended exclusively for the addressee. everis informs to whom it may receive it in error that it contains privileged information and its use, copy, reproduction or distribution is prohibited. If you are not an intended recipient of this E-mail, please notify the sender, delete it and do not read, act upon, print, disclose, copy, retain or redistribute any portion of this E-mail.