gregy - “discovering” plugins the number of p...
“discovering” plugins
the number of plugins available for SK continues to expand- which is wonderful,
however unless you go trawl thru the categories or “all” list, and then try to guess what a plugin might do based on its “name”
.. ive recently found a number of useful plugins - with kind assistance of question/answer from the community;
however i do wonder how plugin discovery could be enhanced…
the categorisations are a start, but even then the lists can be long .. and the names not overly descriptive;
of course you can click thru each plugin “i” button to get the npm description
(or find it on github)
.. but its a bit tedious .. and may discourage new users discovery process .. (even older users like my example … )
or even an understanding of the many extensions to sk functionality derived from plugins diversity ..
throwing this out there for any thoughts.
16 Replies
@Teppo Kurki
hope this is correct place/method .. per yr other mesg
Update the readme with more than a simple summary. There is a standard format on how to provide meaningful content for explaining how to use, install, contribute, etc. anyone can pull request changes to the readme
you mean each plugin's readme? i don't think that helps very much with discovery as readmes are not currently very easy to access - point by grey in the opening, needing to click through to each plugin
we have
Feature How Tos section in the embedded documentation for example https://demo.signalk.org/documentation/features/anchoralarm/anchoralarm.html
As they focus on use cases, solving real world problems they are more user oriented - "here's the use case, here is how it can be solved with SK Server"Anchor Alarm - Signal K Server Documentation
A Guide for users and developers.
i wonder which would be more easy to find and promote more usage:
- expand the readme https://github.com/SignalK/udp-nmea-plugin
- extending https://demo.signalk.org/documentation/features/navdataserver/navdataserver.html to cover also udp
this is a bit special case, as the plugin is included in the default installation..
GitHub
GitHub - SignalK/udp-nmea-plugin: Signal K Node server plugin to se...
Signal K Node server plugin to send NMEA0183 over UDP - SignalK/udp-nmea-plugin
NMEA0183 Server - Signal K Server Documentation
A Guide for users and developers.
but i think writing and promoting use cases and howtos would improve things more than "better (technical) documentation at the source"
one avenue would be to add more plugins to the default install and including their documentation/readme's)to the help system and accessible inline in plugin config
At the very minimum, content in a repository readme is a good starting point. It can evolve as the code evolves. How to guides become stale if it’s not part of iterations in a project repository
You are quite right about docs and code diverging
But even readmes are no guarantee - i just updated a plugin readme when gregy asked about an outdated section..🤦♂️
my ten cents worth ..
Whilst I agree with Tony that better github/npm descriptions woild be prudent in some cases,
I support Teppo second suggestion that expanding /augmenting the sk documentation/how to’s will likely better serve intended outcome to make it easier particularly for newcomers.
- its easier to point them to a single doc/starting point for discovery and help
- the how to’s are focussed around steps to get a particular outcome.
which might require multiple plugins/interactions , & might have more than one plugin/method to achieve outcome
- github readme often assumes a greater level of understanding,
and are certainly not set in the context of a indexed help/user guide (as per doc teppo linked)
- github can be (very) intimidating for the inexperienced.. which is exactly why plugin structure/app store avoids user needing to “go near” github
- the how to could still link to github repository etc
__
signalk documentation (aka the doc linked by teppo)
- what is native format of the documentation/how is it created?
- is there a mechanism for multimuser contributing?
- who/how is moderation done?
Unknown User•3mo ago
Message Not Public
Sign In & Join Server To View
There are ways to generate docs from a code repo that uses markdown for original source documents. This is how many sites keep their docs up to date without them going stale. Doesn’t have to be just a readme, but if I wanted to know how a plugin worked I would start at the readme and hope it pointed me to further documentation from there
docs are in git, simple markdown files (plus images). authoring/review (moderation implies something different i think..) by github pull requests, see for example https://github.com/SignalK/signalk-server/pull/1781
good point on multiple plugins needed for some things
hmmm. im confused already, and maybe im representing “mr average “ here..
not trying to be critical of all the great work, just presenting the mr average perspective, stepping back and looking at
all the docs and info “out there”
… dont shoot the messenger .. (DSTM)
1) if i find www.demo.signalk.org … i might then find the documentation tab, and then see the file you linked above..
“the DOC”” …. ok so far,
except i had to find demo.org.sk .. and know to look under documentation tab to see “DOC”
2) if i find github signalk-server… i see a lot of information… and many many links,
including one to the documentation “DOC” above.. (but there are a LOt of links on the page to get thru for a “newbie”)
some of the info appears to be replicative to “DOC”?
3) there are links on github description to FAQ’s page … albeit this is also in “DOC”, with lots of other stuff.
4) if i find signalk via a google search, i might end up at www.signalk.org.
however info on this page is “different” or “replicative” .. of stuff on github and in the “DOC”
.. and perhaps “aged”?
i realise this has grown over time .. and keeping it syncd/updated is no small task.
…which brings me back to the somewhat intimidating “github” documentation “process”
.. which no doubt works well (when you understand it) … along with quirks, constraints (friendliness .. not?) etc of “markdown” editing..
but for sure, given the investment in effort to date and that most? of documentation is github &/or markdown origin, then this is best to persist with at this time. maybe there is a bigger picture and roadmap (that im not privy to) to make this less “disjointed” for discovery, documentation. FAQs etc … but looking from my perspective.. well im confused, and im not a newbie to signalk… (DSTM)
but for sure, given the investment in effort to date and that most? of documentation is github &/or markdown origin, then this is best to persist with at this time. maybe there is a bigger picture and roadmap (that im not privy to) to make this less “disjointed” for discovery, documentation. FAQs etc … but looking from my perspective.. well im confused, and im not a newbie to signalk… (DSTM)
Documentation format markdown, the source of which is in the
docs/src folder of the server repo.
Interestingly, the goal of the documentation was to try to centralise the information and links so it was the first stop for users (especially new ones).
Clearly we have more work to do to
both with content and discoverability.so now the (obvious ) question from my side ..
How can I help?
Ive had some minor experience with markdown, and i understand github basics (did it for my own page’s repositoies)
.. albeit need to better understand the collaboration/push/pull yada yada of github for multi user & other’s repositories.
and perhaps we should have a channel? or thread? specific for this? (albeit we dont want to confuse everyone with another “documentation” label 🙂 floating around .