Would be really awesome if the Particle Firmware docs were available as a Dash Docset like the Arduino docs are: https://kapeli.com/docset_links
More info: https://kapeli.com/docsets
-J
It would be really awesome if the Particle docs (particularly the API docs) were available as a docset in Dash:
https://kapeli.com/dash
-J
First of all, apologies that your previous post has gone unanswered. I had seen it at the time, but hoped someone with more insight would chime in. Since thatâs evidently not the case, Iâll give you my perspective on the matter.
After looking at the Dash page for a couple of seconds, I get the impression that itâs Apple only. I own both an iPad and an iPhone, so nothing against Apple, but I havenât got a computer from the lovely lot. That means I wouldnât have access to those docs. âWell, then at least Apple users can use themâ, you say, which is a reasonable argument. Unfortunately, the developer community is not limited to Apple only devices, and a lot of people are developing on either Windows, or some kind of Linux distribution as well. Those would then also be excluded. âToo bad, but Dash is really niceâ you say, and Iâd have to agree. In an ideal world, theyâd be available there to make it more comfortable for those developing on Apple.
However, as it stands, the world is unfortunately not a perfect one, and resources are limited. There are only so many folks available at Particle, and time they have to spend at the Docs, is time they canât spend on improving the ecosystem. âTheyâll have to write docs anyhowâ, you say, which is, again, true. Unfortunately, that takes a lot of time and effort as it is already. Having to keep an alternative set of documentation updated, and synced to the main docs, would only add to that âburdenâ. Not only does that increase workload, but itâs also prone to errors. Changes that arenât carried through to both docs sets, and god knows what else.
All thatâs to say that: Lovely if theyâd be in Dash. But if there isnât an easy way (minimal/no human interaction) to get them in there, an more importantly, keep them up to date, I think itâs not that feasible, nor desirable. Iâd rather have one decent online docset that can be accessed by everyone, than a bunch of outdated, fancy, platform specific ones.
That said, If thereâs a way to import them to Dash, feel free to share that knowledge. Better yet, give it a try, since the docs are open source. If you feel you can make a meaningful contribution, please donât hesitate to do so!
In the short-term however, how about enlightening us about what exactly is so âreally awesomeâ about Dash? Maybe some of those features could be incorporated in the particle docs as well.
Iâm not expecting Particle to maintain 2 sets of docs. The Particle online docs appear to automatically generated from some type of source filesâŚwhich if the sources use any of these formats, would be very easy to also ship to Dashâs Github repo for automatic inclusion and updating (someone already does this for Arduino in Dash):
Supports AppleDoc docsets
Supports Doxygen docsets
Supports CocoaDocs docsets
Supports Python / Sphinx docsets
Supports Ruby / Yard docsets
Supports Javadoc docsets
Supports Scaladoc docsets
Supports GoDoc docsets
Supports Elixir / HexDoc docsets
Supports DartDoc docsets
Supports Haskell / Haddock docsets
Supports Any HTML docsets
Itâs not about making your docs comfortable for Apple folks, it just about bringing Particle docs into a tool used by a lot of professional developers who happen to use Macs.
Whatâs awesome about Dash for professional developers like myself is having all of the docs for every language, platform and tool you use to do your work in one tool with built in indexing and offline access. The latter of which is particularly nice when youâre working on code away from the Internet.
No matter whether Iâm checking an nginx config on a server, Makefile syntax locally, or C library syntax, I can type Command+; and quickly search for whatever documentation on whatever I need clarification on, across disciplines.
Anyway, if itâs going to be a real hassle for the Particle guys, I wouldnât expect them to do it, but as noted above Iâd be surprised if the source files arenât already in a Dash-friendly format that can be easily shipped over.
-J
If I'm not mistaken, the content is in .md files (markdown?), which can be found here: https://github.com/spark/docs/tree/master/src/content
Not sure how easy that is to implement, but if you know how, feel free to share, or give it a try.
Thus excluding non-apple developers from that 
I get it though, don't worry. I'm not arguing on the fact that it would be nice to have it in Dash (or any other programmer friendly program, for that matter).
Like I said, if it's easy to import and maintain, then it would definitely be beneficial, or at least more attractive I reckon. It's just that I'd rather see development time go into something everyone can benefit from, rather than just a single platform (however big/professional that might be).
That said, try to convince me, or rather Particle, on why effort should be put into this. The more attractive you make it, and the less work it costs, the more likely it is to be implemented. The way it currently stands I think it's somewhere low on the backlog, considered more a "nice to have" feature. There are so many things that have to be caught up with, and so many new cool features that could be implemented, that a platform specific duplicate doesn't score too high on the "WANT!" list for me. Prove me wrong ;)?
Iâve made my argument for it. Let it land where it may. Are you on the Particle team?
Fair enough.
Nope, just an overly-enthusiastic community member on which they slapped an "elite" title since we spend way too much time on here
2 Likes