Dash Docset for Photon/Core firmware docs?

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

https://kapeli.com/docsets

-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 :wink: 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 :wink:

2 Likes