Fork me on GitHub
#cljs-site2016-05-02
>
pre19:05:17

I scanned through the css source of cljs,info yesterday. ~2000 lines for a cheatsheet and many more cljs code for a single page, seems like an overkill. We can strip that down by moving to garden and revisiting the designs for an interactive page. I would get rid of popups as they don’t work well on phones, and having a mobile first interface will be important. Regarding the site layout and hierarchy, I would recommend we focus on a single getting started guide, cheatsheet, reference to tools and curated libraries, and cookbooks. We should store the content in gh-flavored markdown in a separate repo. I’m sorry I couldn’t spend more time on it yet. but I can this week. @shaunlebron did you have any specific plans for the site?

shaunlebron20:05:56

i haven’t looked at cheatsheet css yet

shaunlebron20:05:17

i think tooltips are good for desktop

shaunlebron20:05:44

i guess we can talk about mobile

shaunlebron21:05:10

my plan for the site is currently to get the api docs navigable and looking good

shaunlebron21:05:58

i’ve been operating on the assumption that api docs are the most frequently used and referenced thing for current users, so that part should be really, really good

shaunlebron21:05:23

i’m envisioning a namespace bar on the left of the docs for navigation

shaunlebron21:05:33

once that’s done, then it’s immediate value for current cljs users, that can setup a positive feedback loop of contributions to add more examples, descriptions to the api doc entries

shaunlebron21:05:27

the getting started guide has been rewritten so many times by different people

shaunlebron21:05:32

i’ve been working for a week on a standard config proposal to be shared by the different cljs tools at #C13B4NQDP

shaunlebron21:05:11

I think that’ll help us write a getting started, but it’s not something I will focus on yet

shaunlebron21:05:43

primary focus for me is to create a first-class cljs api docs site, like clojuredocs but better

shaunlebron21:05:24

typography/design help on that and the news section would be a great start I think

pre21:05:12

Did you speak to any cljs beginners to conclude that "api docs” are the most important asset?

pre21:05:58

I’m happy with https://clojuredocs.org. Perhaps, I’m missing what you mean by better cljs docs site, given the docs are 95% identical.

shaunlebron23:05:48

that's part of what i've been struggling to communicate

shaunlebron23:05:31

in lieu of learning syntax, the only thing left to learn about the language is idioms, which is all api docs

shaunlebron23:05:06

and if the experience of reading api docs is in another language's territory, the core of the experience feels second-class

shaunlebron23:05:26

clojure docs has no syntax docs and examples

shaunlebron23:05:36

no history information of when symbols are made available

shaunlebron23:05:48

and have java interop where js interop should be

shaunlebron23:05:47

not to mention lack of context of what is available in clojure and/or clojurescript

shaunlebron23:05:24

cljs has a lot more things in it than we think, especially protocols, types, and the entire compiler API that is of course missing from clojuredocs

shaunlebron23:05:55

it's all of those reasons

shaunlebron23:05:48

as far as talking to new folks, I've seen a lot of reactions from the folks we tried teaching at the last company I worked at

shaunlebron23:05:41

none of it was particular to api docs, but lack of a website came up, and I'm presuming the whole thing about deferring to another language's api docs as a weak point

shaunlebron23:05:08

anyway, it's stuff i've been working on since dec 2014, it's all done, it just needs to be presented

pre23:05:03

Is this different from your other project that now has a Dash plugin? You’ve done a lot of work on the

pre23:05:01

In other words, how is the site different from the api-docs?