Re: Next steps to improve Interledger's technical side learning curve

Thanks for bringing this up Juan Carlos, yes we should definitely work on
that. Here are a few more recent documents that different people are trying
to improve at the moment:

* https://github.com/interledger/rfcs/pull/224/files
*
https://github.com/interledger/rfcs/blob/master/0010-connector-to-connector-protocol/0010-connector-to-connector-protocol.md
* Adrian is preparing a diagram of how the three processes of ilp-kit talk
to each other, that will be very helpful as well, probably.
* In the coming weeks, I'll add more server API debugging tools to
connectorland as well, one thing I was thinking would be good to add would
be a live log of how connectorland tries to talk to your server, and then
you can see if any of the responses are unexpected, and it can point to
ways of improving.


Cheers,
Michiel.

On Wed, Jun 14, 2017 at 6:35 PM, Juan Carlos Gallardo <
juan.carlos.gallardo@everis.com> wrote:

> 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.
>

Received on Friday, 16 June 2017 10:19:34 UTC