Create tutorial from scratch ?

[jpic]

I'll start this with an anecdote: when I rewrote django-dynamic-fields into facond, I still had Form/Rule/Action/Conditions. When the code got to the point where i was satisfied with it i wrote the tutorial. This is how I figured this lib had just no need for the "Rule" component. Hopefuly, both python and js had serious unit test coverage, so I just removed the Rule stuff from Python and JS, changed all function signatures, and kept on fixing stuff until tests passed again. This strikes me: if i had started by writing the tutorial, I would not have wasted my time TDDing a component that I actually didn't need (the kind of things that would make me look silly in a retrospective right ? haha).

Currently, there's a lot of research documentation about low level components, a bit how "how it could be done", but isn't a lot of the fun about designing how we're going to use this package at a high level before digging into lower level components ?

Perhaps someone with experience about what this package is about (ie. has coded this kind of patterns in private or open source projects in the past) could write a tutorial for using this package ? yes, that means inventing the high level API from the top of their head for using the components which don't even exist yet ?

Sincerely hope this helps but if this doesn't make sense to you feel free to close ;)

FTR: How I failed at documentation driven design

[artcz]

Hi @jpic

I've tackled the problem of API design for this at django under the hood 2016; I've made some notes I believe I've never published, I'll try to find it and organize it into some sort of initial onepager later this week.

Thanks for bringing that up. :)

[mjtamlyn]

I am a fan of DDD (rather than exclusive TDD). It's an interesting one here because the "second level" (see #24) of the API is almost more important than the top one, and half of the point is that you can have multiple top level APIs which are created or create the same underlying infrastructure. For example, a (near) compatible version of the existing forms.Form API would be fantastic for adoption. But I get ahead of myself 😉

[jpic]

Oops sorry for duplicating #24...

@artcz thanks that'd be really nice !

Django forms compatibility or even declarative metaclass style are not a requirement for me, perhaps it will be easier to design the API if we don't think about it for now, I see no reason why that could not be added later, be careful @mjtamlyn because sometimes dreams come true even though I'm sure people will happily migrate away from forms.Form if adapters is definitely better ;)