This page is not created by, affiliated with, or supported by Slack Technologies, Inc.
2016-05-02
Channels
- # admin-announcements (4)
- # aleph (10)
- # arachne (1)
- # beginners (66)
- # boot (19)
- # cider (6)
- # cljs-edn (2)
- # cljs-site (32)
- # cljsjs (4)
- # cljsrn (32)
- # clojure (116)
- # clojure-austin (6)
- # clojure-belgium (2)
- # clojure-dusseldorf (1)
- # clojure-russia (16)
- # clojure-uk (5)
- # clojurescript (178)
- # community-development (2)
- # cursive (28)
- # datascript (16)
- # datomic (16)
- # dirac (13)
- # editors (2)
- # emacs (1)
- # error-message-catalog (30)
- # events (3)
- # garden (2)
- # hoplon (27)
- # jobs (4)
- # ldnclj (4)
- # liberator (3)
- # off-topic (6)
- # om (49)
- # onyx (24)
- # parinfer (9)
- # re-frame (59)
- # reagent (46)
- # remote-jobs (1)
- # rethinkdb (4)
- # rum (2)
- # slack-help (11)
- # untangled (13)
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?
i haven’t looked at cheatsheet css yet
i think tooltips are good for desktop
i guess we can talk about mobile
my plan for the site is currently to get the api docs navigable and looking good
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
i’m envisioning a namespace bar on the left of the docs for navigation
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
the getting started guide has been rewritten so many times by different people
i’ve been working for a week on a standard config proposal to be shared by the different cljs tools at #C13B4NQDP
I think that’ll help us write a getting started, but it’s not something I will focus on yet
primary focus for me is to create a first-class cljs api docs site, like clojuredocs but better
typography/design help on that and the news section would be a great start I think
Did you speak to any cljs beginners to conclude that "api docs” are the most important asset?
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.
that's part of what i've been struggling to communicate
in lieu of learning syntax, the only thing left to learn about the language is idioms, which is all api docs
and if the experience of reading api docs is in another language's territory, the core of the experience feels second-class
clojure docs has no syntax docs and examples
no history information of when symbols are made available
and have java interop where js interop should be
not to mention lack of context of what is available in clojure and/or clojurescript
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
it's all of those reasons
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
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
anyway, it's stuff i've been working on since dec 2014, it's all done, it just needs to be presented