Create README.md #30

smaramba · 2016-11-03T15:31:53Z

@bolismauro @lucaquerella here the first draft of the readme.
I've looked at pretty much every readme of every significant swift framework, this is (excluding the copy that is work in progress) my best summary of what a readme should contain.
feel free to suggest or question everything.

my suggestion on how to improve this:

improve copy
insert/update the items in the roadmap (under features)
introduce also the advanced stuff (i.e. asyncActions)
tune the example to something comprehensive that we will also release as a complete example
include more examples, even complex ones

bolismauro · 2016-11-03T15:37:50Z

README.md

+
+## Overview
+
+### defining the logic of your app


I'd start with a very basic snippet that users can copy/paste and try katana (the UI probably).
20 lines max, something very simple

You can use Katana elements of course

bolismauro · 2016-11-03T15:38:24Z

README.md

+you can ask the `Store` to be notified for every change in the app state
+
+```swift
+store.addListener() {


I'd avoid to use this example. It is really something we don't want to see in applications :)

bolismauro · 2016-11-03T15:39:53Z

README.md

+
+## Overview
+
+### defining the logic of your app


I'd start with the UI, since it is the thing you see first.
It is also easier to explain. "this is how you can create the UI, need the logic? ok let's add it"

smaramba · 2016-11-03T16:18:42Z

after a discussion with @bolismauro we decided the things to change for the next iteration:

move the feature section at the end, changing name to 'roadmap'
create a small complete app (max 20 lines of code) as a first thing of the quick start section

smaramba · 2016-11-03T16:36:22Z

after a discussion with @lucaquerella we decided that:

we need to lower down the references to redux/react
remove the store.addListener reference
remove the table from the code snippets

Add sample project

smaramba · 2016-11-08T16:45:44Z

moved Roadmap to the end
only one reference to redux/react
removed the addListener { table.reloadData() }
changed the quick start to not include table

bolismauro · 2016-11-08T21:07:06Z

Some feedback

Titles should be uppercase
I'd change in a Katana app all the state is entirely described by a single serializable data structure and the only way to change the state is to emit an action. in is to dispatch an action. Dispatch in general is the correct verb (and the one we use in the implementation)
UI: in a Katana app you define the UI in terms of a tree of components declaratively described by props (external world) and state (internal world). This approach lets you think about components as an isolated, reusable piece of UI, since the way a component is rendered only depends on the current props and state of the component itself. I'm not sure if we need to push more on the no mutation thing here
<3 heart smile here :D
In Katana you declaratively define your UI components through NodesDescriptions. Not sure here how to put the protocol name plural, but NodesDescriptions is not correct in my opinion
When it's time to render the component, the method applyPropsToNativeView is called, this is where we need to adjust our nativeView to reflect the props and the state. It is not needed for this example. Should we skip it? If we want to show the applyPropsToNativeView maybe we can find another way? (e.g., background color?)
add a section how to contribute. I would mention PR and maybe swiftlint

smaramba · 2016-11-09T08:32:46Z

uppercase titles
emit -> dispatch
<3 -> ❤️
NodeDescriptions -> NodeDescription (updated copy)
explained that applyPropsToNativeView is not necessary in the example
created a Contribute section, we should create a CONTRIBUTE.md file with all the details. I'm opening an issue for that

smaramba · 2016-11-09T15:39:06Z

removed repetitions of the in katana... pattern inside the bullet list at the beginning
added reference to plastic
added bullet list to explain the StateType, PropsType and NativeView
updated the example with the Renderer

Updates on the copy

bolismauro · 2016-11-09T16:43:00Z

In the Defining the UI section
- first snippet. We need to add Keys that has been added by Refactor animations #35
- second snippet. We need also alpha and key. NodeProps is changed to NodeDescriptionProps
- third snippet. We decided to use the typealias in the signature (I'd stay consistent with the examples). We also need to set the alpha to the native view
- fourth snippet. We decided to use typealias in the signature
in the Attaching the UI to the Logic section
- first snippet. We decided to use typealias in the signature
In the Layout of the UI
- first snippet. We decided to use typealias in the signature
- I'd also add (again) a Plastic link. Something like "for more information about the philosophy...". We can decide to add it at the bottom (e.g., in where to go from here)
- let rootView = views.nativeView I'd call it nativeView

Suggestions for roadmap:

Declarative table (link feature as soon as it is available)
MacOS (link feature as soon as it is available)
Improve testing
Expand documentation

Besides these points, SGTM

bolismauro · 2016-11-09T17:17:36Z

@smaramba I'd also remove the StackOverflow thing at least at the beginning.
We can use issues to start with

bolismauro · 2016-11-09T20:19:12Z

@smaramba remember to update the headers according to #50

lucaquerella · 2016-11-09T20:44:48Z

Great job here. <3

Suggestions:

Remove <-> in the first section (you can use ↔️ for example)
For coolness sake add a table with the pro of using katana - similar to what you can find here: https://github.com/fastlane/fastlane (Suggested by Dr. Bolis)
Add a section where you describe the animations, I'd add a gift that shows the Pokemon example

lucaquerella · 2016-11-09T22:01:41Z

@marcopaz (aka Paz) make me notice that the logo is not high resolution. can we fix it?
he also spotted a typo:

logic: app all the state is entirely described

smaramba · 2016-11-10T09:25:00Z

yeah I'm asking tomasz to give us the @2x version

smaramba · 2016-11-10T10:14:19Z

moved the Installation section under Overview
Removed <-> in the first section (used ↔️ instead)
removed typo logic: app all the state ...
added alpha and keys to the props
renamed NodeProps -> NodeDescriptionProps
enforced the typealiases inside the applyPropsToNativeViewmethod signature
added alpha to applyPropsToNativeView
enforced the typealiases inside the childrenDescriptions method signature
enforced the typealiases inside the connect method signature
enforced the typealiases inside the layout method signature
added reference to Plastic even in the Layout of the UI section
renamed rootView -> nativeView
included in the roadmap the suggestions from @bolismauro
removed the stackoverflow section

TODO:

add table with PRO (in progress)
add @2x logo (waiting asset from tomasz)
introduce animations (including pokemon example) (in progress)

mdanieli · 2016-11-10T13:49:24Z

README.md

+
+## Contribute
+
+- If you __found a bug__, open an issue


If you found -> If you've found (once again, it doesn't say when the bug was found)

mdanieli

Added comments and fixes.

bolismauro · 2016-11-10T16:05:29Z

README.md

+| :muscle:            | Use support for middleware like Logging  |
+| :tophat:            | Automatically update the UI when your app state changes |
+| :triangular_ruler:  | Automatically scale your UI to every size and aspect ratio |
+| :horse_racing:      | Animate all the UI changes               |


What about Easily animate UI changes?
I'd also add something about the one way data flow. I think it is important

bolismauro · 2016-11-10T16:08:53Z

README.md

+          labelProps.key = CounterScreen.Keys.label.rawValue
+          labelProps.textAlignment = .center
+          labelProps.backgroundColor = .mediumAquamarine
+          labelProps.text = NSAttributedString(string: "Count: \(props.count)", attributes: nil)


I think you can just use labelProps.text = NSAttributedString(string: "Count: \(props.count)")

Move Logo inside Assets

# Conflicts: # Demo/Actions/DecrementCounter.swift # Demo/Actions/IncrementCounter.swift # Demo/AppDelegate.swift # Demo/Assets.xcassets/AppIcon.appiconset/Contents.json # Demo/Info.plist # Demo/State/CounterState.swift # Katana.xcodeproj/project.pbxproj

smaramba mentioned this pull request Nov 3, 2016

Write a great README #21

Closed

bolismauro reviewed Nov 3, 2016

View reviewed changes

smaramba force-pushed the feature/readme branch 2 times, most recently from bf4f292 to b79139e Compare November 7, 2016 16:03

smaramba added 2 commits November 8, 2016 14:15

Create README.md

9de379b

Lower down references to react/redux

5533403

smaramba force-pushed the feature/readme branch from b79139e to 5533403 Compare November 8, 2016 13:16

smaramba added 4 commits November 8, 2016 16:21

Add katana logo

bbefbb6

Add katana logo to readme

47e8803

Add sample project

Center header image

ce66dc4

Update copy

41f4f7d

Update README third iteration

e6bccdd

Update counter.gif

e31a637

Update the readme using Renderer

69b8cf3

Updates on the copy

Readme iteration

9be4964

smaramba added 2 commits November 10, 2016 11:57

Add Table

3a452b2

Update copy

45cd8f6

mdanieli reviewed Nov 10, 2016

View reviewed changes

smaramba added 3 commits November 10, 2016 15:02

Add new update for README

393880e

Rename CounterScreenProps -> PropsType

bd10e0a

Add PlasticNodeDescription and PlasticReferenceSize

83aca7a

bolismauro suggested changes Nov 10, 2016

View reviewed changes

Update README to react to MB comments

d6dc20d

bolismauro approved these changes Nov 10, 2016

View reviewed changes

smaramba and others added 20 commits November 11, 2016 09:42

Update the README to improve logic <-> UI paragraph

0096287

Add changes reacting to LP feedback

6ee899e

Introduce Sync and Async actions

5aa6f8c

Move Logo inside Assets

Update logo

a48bce4

Add examples

8589d7d

Add codingLove demo

a6cce20

Rename codingLove image

6a136ac

Rename codingLove asset

163ec4d

Add link to codingLove example

ddcf219

Add link to the documentation

4b8beef

Add twitter handles

69d04c1

Update counter image

218435b

Rename counter asset

22763d4

Change size of the example link

8042fde

Move example description on top of the image

ac998ac

Remove duplicated example from table

8ce2d18

Update Readme with corrections

dbae152

Change Efficiently -> Automatically

41ba5b2

Update Katana GitHub name

fb86ffb

bolismauro merged commit 9807029 into master Nov 11, 2016

bolismauro deleted the feature/readme branch November 11, 2016 16:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create README.md #30

Create README.md #30

smaramba commented Nov 3, 2016 •

edited

bolismauro Nov 3, 2016

bolismauro Nov 3, 2016

bolismauro Nov 3, 2016

bolismauro Nov 3, 2016

smaramba commented Nov 3, 2016

smaramba commented Nov 3, 2016

smaramba commented Nov 8, 2016

bolismauro commented Nov 8, 2016 •

edited

smaramba commented Nov 9, 2016

smaramba commented Nov 9, 2016

bolismauro commented Nov 9, 2016

bolismauro commented Nov 9, 2016

bolismauro commented Nov 9, 2016

lucaquerella commented Nov 9, 2016 •

edited

lucaquerella commented Nov 9, 2016 •

edited

smaramba commented Nov 10, 2016

smaramba commented Nov 10, 2016

mdanieli Nov 10, 2016

mdanieli left a comment

bolismauro Nov 10, 2016

smaramba Nov 10, 2016

bolismauro Nov 10, 2016

smaramba Nov 10, 2016

Create README.md #30

Create README.md #30

Conversation

smaramba commented Nov 3, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

smaramba commented Nov 3, 2016

smaramba commented Nov 3, 2016

smaramba commented Nov 8, 2016

bolismauro commented Nov 8, 2016 • edited

smaramba commented Nov 9, 2016

smaramba commented Nov 9, 2016

bolismauro commented Nov 9, 2016

bolismauro commented Nov 9, 2016

bolismauro commented Nov 9, 2016

lucaquerella commented Nov 9, 2016 • edited

lucaquerella commented Nov 9, 2016 • edited

smaramba commented Nov 10, 2016

smaramba commented Nov 10, 2016

Choose a reason for hiding this comment

mdanieli left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

smaramba commented Nov 3, 2016 •

edited

bolismauro commented Nov 8, 2016 •

edited

lucaquerella commented Nov 9, 2016 •

edited

lucaquerella commented Nov 9, 2016 •

edited