I took some time to document Select now that it has a stable release. We already had an overview and module documentation, but I wanted to add some more tutorial-focused content as well as some explanation-focused content around some of the unfamiliar ideas in the library.
If any of you folks give this a read and notice ways it can be improved (too much information? too little? typos?) I would appreciate the feedback!
In addition to writing this documentation, Iāve set up a continuous integration process that builds the documentation site, which is itself quite full-featured. Iāll soon write about this process as itās quite easy to have a beautiful, functional docs site hosted on GitHub pages for your library.
The general idea is that by lowering the difficulty to set up a documentation project like this we can make it a little easier to get started documenting your own libraries.
Wow Thomas this is looking great! I can hear your tone coming through, especially with this
Effect rows can be surprisingly finicky to get right
Yeah?? hehe wonāt you be glad when Halogen is ready for 0.12
Ok some bits of feedback:
Small detail: Writing useful item types info box needs a newline to get code highlighting
Lines 28-40 of Feedback are a little confusing in the formatting, maybe it would be a good idea to refactor some helpers into let/where bindings? In general itās easy for Halogen code to get messy like that ā¦ small functions are good! (so I say after writing a run-on sentence)
In your Project Setup tutorial you write
return the next query
I realize that phrasing is used elsewhere, but I think itās inaccurate ā¦ really itās just returning whatever was trapped inside the Query, and most of the time thatās actually unit (in event handlers, etc.). The exceptions would be EventSources (which return Listening status) and when youāre actually querying a component with H.queryand want useful information out of it (;
But I donāt want to make a big deal out of that. Honestly the documentation looks great to me
Shoot! Halogen is already ready for 0.12, so I guess I can go ahead and remove all that stuff. I should have waited a week to write this
Right. Iāll fix this.
On reflection I think youāre right. I didnāt want to spend too much time changing the shape of the code from section to section because I find it difficult to keep track of these sorts of changes when I read tutorials. We discussed this a little on Slack ā code tutorials fall down often because you donāt see the entire file at once, just a small window onto a few lines of it, and so without that context it can be tough to keep track of whatās happening. I tried to stick with the minimal number of changes necessary to get the whole thing working, but in the code youāve called out here, it becomes tough to follow such a dense function.
Iām going to refactor it into renderItem, renderContainer, renderInput as I usually do in my own code.
Youāre right here as well. Early into learning Halogen I thought of it as returning the ānextā query, largely because of what you stated there: most of the time itās actually unit, in which case the next query runs. However, weāve used H.query often enough that I should have known better when writing this! Iāll fix this as well.
@RathishB23 You might choose a few libraries that you are currently using and reach out to the owners or most frequent contributors to ask how you might best contribute documentation to that library. Youāll be helping yourself as a user as well as helping others!
As far as the documentation you contribute goes, I think that cookbook-style content is sorely missing ā the kind that demonstrates how to use a library to accomplish some task, rather than documentation that simply describes the concepts in the library or summarizes a few functions. The documentation for select does this by walking through how to build a dropdown and a typeahead using the library.
For example, the Argonaut libraries could really use some examples of how to decode and encode different JSON structures.
