Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft and directions #1

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Draft and directions #1

wants to merge 4 commits into from

Conversation

nickbalestra
Copy link
Collaborator

@nickbalestra nickbalestra commented Nov 7, 2016

@staltz, @Widdershin, @TylorS, @vic, @geovanisouza92, @FeliciousX, @raquelxmoss :

I've drafted a first early readme. Few things that are perhaps worth discussing:

  1. Publishing: I would love to keep it always published it here while being able, whenever it make sense, to use some of its contents elsewhere (i.e: on the cycle.js wiki), as well as being able to publish it elsewhere (Leanpub, Gitbook,...).
  2. Table of contents: I've jotted down a very initial draft:
  • Preface
  • Chapter 1: Data streams
    • The Observable Type
    • Creating observables
    • Composing observables
    • Streams libraries
  • Chapter 2: Cycle.js
    • Hello World
    • Model View Intent
  • Chapter 3: Handling side effects
    • DOM Driver
    • HTTP Driver
  • Chapter 4: Testing
  • Chapter 5: Fractal Architecture
    • Components and nested dialogues
  • Chapter 6: State Management
    • Onionify
    • Cully
  • Chapter 7: Advanced Patterns
  • Chapter 8: Routing
  • Chapter 9: Full reactive stack

I guess it will evolve as we move forward with writing this. Would love to have your feedback on this, is there anything you see missing? Will you suggest a different order?

  1. Anything else to discuss before I move forward with this project?

@raquelxmoss
Copy link
Member

✨ This looks like a solid base to get going with!

One thing that I would like to see (though you might have a good reason for not including this), is a section on creating your own drivers, that covers when, if, and how to create one.

I imagine that Chapter 6: State Management will evolve a lot throughout. I anticipate that new libraries for state management will emerge as we go. Perhaps there could also be something on patterns for state management without libraries (that might not necessarily involve components).

@Widdershin
Copy link
Member

I would love to contribute a chapter on developing games with Cycle.js.

I think we need a really solid chapter on testing (which would probably also involve us collectively figuring out how best to test Cycle apps, which really needs doing).

@geovanisouza92
Copy link
Member

I agree with @raquelxmoss, a chapter about drivers would make a lot of sense.

State management could be written talking about the simplest approach (reducers/actions inside components) going through more radical approaches (like state drivers) and letting the user choose.

Maybe I could contribute a little with Cycle.js for 3D/canvas.

@nickbalestra
Copy link
Collaborator Author

@raquelxmoss, @geovanisouza92 totally agree, I will add a section on chapter 3 about creating your own drivers. Yes, I see the whole index mainly as the direction to follow, evolving as we move further with the writing. In this direction one good way to go will be to review each chapter TOC in detail just before we start writing it so that we define such details as we tackle each section.

@Widdershin, @geovanisouza92 that will be totally awesome!

@TylorS
Copy link
Member

TylorS commented Nov 8, 2016

Seems like a very good start. I'd love to contribute when I've got a little more free time, I'm particularly keen on helping with the routing.

@nickbalestra
Copy link
Collaborator Author

I got in touch with some Publishers that might be interested in publishing such a book. I haven't made my mind up yet if I should go down this path or not and stick with writing it here within the community instead. So, for the moment , I'm taking some of the inputs publishers are giving me, by doing the initial work they require an author to go through. First of all putting together a detailed outline/proposal document that I'm sharing here below with you. I believe that either way I go, starting from "why" and clearly define "what" is vital for the success of the project.

I would love to hear any feedback from you (as well as your thoughts on writing it here vs going with a classic publisher).

Many thanks in advance!


Title: Cycle.js

Build reactive Human-Computer Interaction(HCI) applications that are easy to extend, compose and test, with cleaner code and greater separation of concerns

Audience

Reader’s expected knowledge

  • General knowledge of front-end development
  • Familiarity with HTML, CSS, and JavaScript
  • Familiarity with ES2015
  • Familiarity with using the terminal to install and run npm packages in a Node.js environment.
  • No experience with functional programming
  • No previous knowledge about Observables
  • No experience with RxJS or any other functional reactive stream library

Reader’s motivation

Learn how to create reactive Human-Computer Interaction(HCI) applications that are easy to extend, compose and test, with cleaner code and greater separation of concerns.

Mission

About the book’s topic

The book focuses on Cycle.js: A functional and reactive JavaScript framework for cleaner code.

How Cycle.js works and what makes it different from its alternatives

While most front-end frameworks focus on Graphical User Interfaces, Cycle.js introduce a message passing architecture to model Human-Computer Interaction(HCI) in a more holistic way, making it suitable to create any kind of Human-Computer Interaction like Web Audio components and network requests components just to name a few.

To do so, Cycle.js glue together functional and reactive programming paradigms exposing an architecture for cleaner code and greater separation of concerns. Apps are created as pure functions, making aspects like testing and server-side rendering trivial. Their internals are built around Reactive programming constructs, resulting in greater separation of concerns and cleaner, simplified code related to events, asynchrony, and errors.

Because of its fractal architecture, every Cycle.js app, is simply a function that can be reused in any other Cycle.js app.

Why is it important now?

Observables are here to stay.

Netflix is partly built around them. They are used as primitives in various reactive streams libraries (i.e. RxJS) and can be found in various codebases: from Angular2 to Falcor, from Horizon.io to Mobx. An ECMAScript proposal for Observables is now at stage0. Yet, put aside books focusing on the RxJS library, It’s hard to find written material explaining how to build real applications with such constructs.

Cycle.js is one of the first fully reactive frameworks to suggest best practices and design patterns around those reactive primitives. Pushing the state of unidirectional data-flow architectures further.

Given the rising popularity of functional reactive programming together with the growing of the Cycle.js community this book represent an important missing piece to help developers master the observable type, easily use functional reactive stream libraries, learn design patterns that can be applied to any Human-Computer Interaction application and write cleaner code that is easier to test and reason about.

About the book

Core issues/challenges this book is going to address

Getting started with Cycle.js and FRP, in general, can scare away developers. Streams can be scary at a first sight, functional programming concepts might sound new and the reactive paradigm forces us to reason in a new way. Furthermore, picturing how to put all this together in order to write better apps can be a non-trivial task adding up developer’s fatigue. Cycle.js and this book address all of this, plus more by taking the readers through a journey aimed to prove those common misconceptions to be wrong.

The journey that this book will take the readers on.

  • Basics of Functional and Reactive Programming: Our journey starts with explaining the Basics of functional and reactive programming, explaining concepts like purity, read/write effects and separation of concerns.
  • Data stream fundamentals: In this part we introduce the reader to the Observable Type, explaining what problems it solves and how can we build stream libraries with it. By the end of this part, the reader will have implemented his own toy version of a functional reactive stream library.
  • Cycle.js fundamentals: Cycle.js framework come with very few concepts to learn. Similarly to what we did in the “data streams fundamentals” part, we’ll go through implementing a toy version of Cycle.js core API in order to explain the problems it solve. By the end of this part, the reader will be comfortable with concepts, like run, drivers and sources/sinks.
  • Cycle.js core: Each chapter in this part of the book will go through building a small project with Cycle.js. Each time we’ll focus on a different specific core aspect:
    • Model View Intent pattern
    • Building reusable components with isolate
    • Building your own Cycle.js drivers
  • Cycle.js advanced: This final part of the book will help the reader mastering Cycle.js by going through advanced and often asked topics
    • Server Sider Rendering
    • Testing
    • State Management
    • Routing
    • Integrating Cycle.js Apps in current projects

Objective and achievements

After reading this book, the reader will be able to:

  • Work with observable sequences.
  • Implement and use functional reactive stream libraries
  • Write clean, pure and maintainable code
  • Create reusable Cycle.js components
  • Write Cycle.js drivers for handling side effects
  • Use server-side rendering to make applications load faster
  • Write tests for Cycle.js applications
  • Master advanced Cycle.js patterns and best practices
  • Integrate Cycle.js alongside current projects

@Widdershin
Copy link
Member

I would love to hear any feedback from you (as well as your thoughts on writing it here vs going with a classic publisher).

A few of us in the community have been approached by publishers. I took the issue to some of my managers from my last company, and they strongly recommended self publishing. Their argument was that the financial deal provided by most publishers means that unless your book is an outrageous success, you're unlikely to see a reasonable return on your time invested. They also pointed out that publishers bring to the table the ability to access and sell to the market. This is a moot point for Cycle.js, between Gitter and Github we already have access to the potential market.

Here a few of my personals pros and cons for self publishing:

Pros:

  • All of the community expertise can be contributed
  • The book can be open source, so people can see how it was built and make contributions
  • You don't have to write it all yourself
  • If the book is sold via a self publishing service the author's cut is much higher
  • No obligation to meet deadlines
  • More freedom in how information is presented
  • More freedom around pricing

Cons:

  • No advance
  • No support from experienced editor
  • No obligation to meet deadlines

Personally, I would rather see the book written in the community and self published. However, I understand that there is a financial component to this. If the book was written in the community and self-published, I have an idea of how to address this:

The lead writer/book creator receives a large direct cut, (say ~50%).
The remainder of the money is put into a collective pool and used to fund community projects.

Some of my friends in Wellington have built a piece of software called Cobudget: https://medium.com/@Cobudget/getting-started-with-collaborative-funding-265dabef30e3#.y601zusw3

It provides a space for people to propose ideas, and then anyone can fund them. The idea is that this would be seeded with a certain proportion of the proceeds of the book.

I would prefer this approach to attempting to reimburse contributors directly, as that has a very large set of social challenges.

This is just an idea, what do you think? @nickbalestra

@nickbalestra
Copy link
Collaborator Author

@Widdershin the points you outline are more or less the same ones I'm evaluating. I am boiling them down to the followings:

Pros:

  • All of the community expertise can be contributed
  • The book can be open source

Cons:

  • No support from experienced editor
  • No obligation to meet deadlines

So far I must say that all my interactions with publishers/editors have been very useful, and I can totally see them bringing great value on the table (not in 💵 ).

Perhaps there might be an opportunity for a solution in between (see @getify's "YDKJS"). I'm currently exploring this path to see if it could be a feasible option for this project as well.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants