request: application developer docs please!

I think we are due a grant proposal for developer docs. This would be api documentation and examples at a mid level, part way between @vtduncan's protocol docs, and @Zach!'s not-technical docs. It should be targeted at people building ssb apps or making PRs to current applications.

There are lots of people who would be good at this!

I'd say that this is basically a shoe-in, obviously a good idea, and pretty much certain to be funded. I mean, you can't have enough documentation!

Awesome! please post some photos of your housebus too!

Challenge accepted =p (with the caveat that I'd need notice of about 1 / 2 months to work out what to do about my current day job.) If the timing worked out, I'd be happy to join you @jolyon.

I think understand the following concepts get you a long way in ssb app development:

• pull-streams
• mutant observables (and composing them into powerful abstractions.)
• Observable backlinks (list of messages that link back to a particular message)
• flume
• patchcore
• depject as used in patchcore, patchbay and patchwork.
• custom renderers for scuttlebutt messages (via dependency injection.)

@mix has already done some great twitch videos on these, but I think written resources / improved API docs would be helpful too =].

I could probably write a tutorial series on those and motivate them in terms of how I do things in ssb-chess with them.

I could also probably try to improve the API docs for mutant',patchcoreandflume` and others as although those are fantastic and powerful abstractions, I had to do a lot of digging to work with them.

If you like, I could try to flesh out what I'd do with the time working on the grant more? I imagine it'll involve communicating with others to work out what we want as well. Especially if some of us are working on it collectively.

yay @happy0, i was hoping you'd be interested in this, i think you'd be really excellent given your experience with the chess app! i think what you've outlined is spot on.

some thoughts that anyone can feel free to ignore: i notice i have a concern about whether we focus the documentation on the "old way" (calling the core sbot methods like messagesByType or createUserStream and filtering / reducing in the stream) or the "new way" (using flume views). i also notice i'm partial to documenting application development using patchcore as opposed to only documenting everything from scratch, since that was the whole point of @matt, @mix, @piet and i investing our time and energy into that work. (i don't mean to say i'm against patchless, it's just not ready for showtime yet.) so this informs why i'm most excited about @happy0 taking the lead.

/cc also @Josiah or @craig or @noffle or @nichoth or @Nina

@happy0 I think I'd take preference for someone who can start work sooner, but I do expect that we'll want fund multiple documentation projects. We'd get a lot of benefit from being a very well documented project. @dinosaur it's not a choice between patchcore and patchless - there is lots of stuff that uses sbot client directly, eg, patchfoo or git-ssb.

@dinosaur it's not a choice between patchcore and patchless - there is lots of stuff that uses sbot client directly, eg, patchfoo or git-ssb.

@dominic

yeah totally. i agree that providing high-quality documentation for the modules in common is the best strategy. i hope patchcore and patchless converge in time with a re-write anyways.

more subtext: i'm also thinking about the target audience who aspires to be an ssb application developer. so far i think we as ssb developers have prioritized making it work, with less regard for how a typical enterprise / web application developer who has only seen traditional patterns and code styles will perceive our systems. i see patchcore as our first direct attempt to address this problem. we tried our best, but it's still confusing as hell for any newbie, wow! what i'm saying is i want to support more efforts in the direction towards an enterprise-level stack suitable for your average developer, by continuing to refine our systems with better documentation, standard code style, dry code architecture, less footguns, etc. so i find it hard to endorse application developers being guided towards what i perceive as making it work and not trying to cater to average developers with traditional mindsets. more directly, i've witnessed far too many people struggle to understand your code @dominic, or seeing @mix in pain trying to refactor code in git-ssb. i think what we've done so far is wonderful, i wouldn't take anything back if i could, but i'm interested in how we evolve from here towards the next step of potential contributors. or maybe i'm totally in my own world, that's entirely possible, but in my defense i pair with more junior developers as my primary paid work.

I'll do my best to help as best I as can to whoever will be working on this.

I don't know the stack and am still at the starting gate in learning it so my contribution would be minimal.

However, I would be very happy to offer a small amount of time proof reading and reviewing for clarity (where my ignorance might be a benefit because if the docs aren't clear, I won't understand).

for the record I'm ready to chip in on patchcore v2. I'd love to pair on this, and really get in and use patchless to see what ideas work well there.

I would be happy to fund a documentation related grant every round, so far we have done so every time, counting "@mixmix helps you build it" which has produced video documentation.