Community Documentation - WIKI

I’ve created a new wiki for ‘community’ documentation for the SSP.

Location

you can find it here: https://github.com/TheTechnobear/SSP/wiki

Coverage

  • module documentation, both factory and 3rd party
  • general ssp information
  • development information
  • tips n’ tricks

Goals

It should be stressed this is design to supplement this forum, not in any way replace it!
as part of this, you will notice I have already been including links back to this forum to appropriate topics.
e.g. if there is a module page here already, I link back to it.

generally, what Id like to do is make sure that I have the appproriate information in the wiki, but link back to ‘discussions’ are on this forum.

Why a community wiki?

  • One place for my module documentation
    this started because I (thetechnobear) needed somewhere to store documentation for my modules, as Ive found it a pain the way Im doing it currently.
    so the structure, Im heading for its. the wiki for documentation and a topic on this forum for discussion.
  • community editing
    I wanted somewhere that anyone can edit the documentation easily.
    my hope is others can contribute to it slowly over time, rather than having to sit down in one sitting for hours to create everything in one go
  • Ease of use
    Im using GitHub, which features a pretty nice wysiwyg editor that runs in your browser, so you don’t need any software or knowledge of ‘markdown’ languages (though, I do use a bit to make it tidier)
  • Open source
    Github is full open, so anyone can fork/clone this wiki (its a git repo) , so it is NOT bound to ME. everything that is contributed can be freely downloaded , this also means it could potentially be moved to another wiki provider, should we decide this is needed later.

Status

I’ve pre-populated it with what was available, but its only a start many things need to be added.
Im also working through the factory modules adding parameters, inputs and outputs.
help needed :wink:

Style

for modules in particular we should develop a ‘style’, so that its easy for users to find things…
I’ll put my suggestions below, but we can work on it together.

Contribution

PLEASE get involved, if we all spent a little time just documenting one or two modules, we would have them all done really quickly !
BUT if you wait for someone else to do it, then it might never get done,
as for me, I will do some work on it (I’ve already put in a couple of hours!) , but bare in mind, Im also doing SSP module development, so I don’t really want to spend all my SSP time doing this !

also don’t let ‘perfection be the enemy of good enough’ ,
the point about wiki, is it can be edited and improved over time… so get started as soon as possible.

How to contribute:

simply go to the above link, and you should see the EDIT button in top corner

it may be you need a GitHub account (its free) and be logged in.

there are tutorials online on how to use, but if anyone has any tips - please share on this topic

for now, you might want to look at a couple of pages Ive already created (e.g SVF, home page)
this show how to :

  • add external links (e.g. to webpage)
  • use tables for structuring
  • link/create new wiki pages with titles

Ive also created a topic with some tips in the wiki on the contributing page

This Topic

please use this topic for discussions about how to use this wiki, things like style… or to help newcomers get starting on contributing.

5 Likes

Style

as above I really do not want :

so the most important thing is to get started, style can be fixed later .
that said, please do not assume someone else is going to sort out your ‘ramblings’, that is not that helpful either :wink:

what is style?
we all know that consistent formatting makes information easier to find and also digest.
if every modules documentation is formatted differently, it makes it really hard for users to get to the information needed.
ideally what we want is something that is both concise (so can be used as reference) , but then later goes into a bit more detail…

I’ve not really thought alot about this yet but my thinking so far is:

  • overview
    a SHORT overview of what the document is , one paragraph
  • resources/documentation
    links to useful forums posts , e.g. if there is already a forum topic on the module
  • parameters
    a list of parameter, and there basic use … keep it brief
  • input/output
    a list of all the input/output parameters, and usage, keep it brief
  • details/how it works
    so more detailed information on how it works…and how the parameters affect it.

the basic idea is the first 3 items here (overview/resources/parameters) are first, as its almost ‘reference’ material, the bits that even experienced SSP users might come back to.
also feel free to avoid repetition, to keep it brief

e.g VCA: A1-A4 - attenuation for VCA 1-4
rather than VCA A1, VCA A2, VCA A3 VCA A4


Next steps

tasks now done!

ok, so the thing I’d like to get done first is

  • get a list of all parameters for all factory/technobear modules.
  • get a list of all io for all factory/technobear modules.
  • update forum links
    I only found a few topics for factory modules, but I think there are probably other useful forum topics we can link to
  • grab some details from forum
    I have written some topics/posts on things like the BUS module, Id really to to ‘capture’ these, at least to give some basics to the BUS module documentation

Ive started this on some modules… you can see a few like SVF as examples.

I’ll keep pluggin away at the parameters, and input/output until I get bored/fed up.

I’ll likely do the simpler ones first, if someone wants to do the ones with lots or parameters , ins and outs … even if you just list them - that’ll be cool, as it’ll save me some work.

please note: check on the SSP… as Im not 100% sure docs on the forum are all up to date… Ive not checked. (though the forum does contain good description for parameters for some modules)

community participation…
the basics are now all in place…what we now need to do is to extend the descriptions, and also give better explanations of how to use the various modules.
this can be a gradual process, as we slowly improve the resource.

this can only happen if the community gets involved , just a small amount of time here and there from you will add up, to make this documentation what you need and hope for.
this cannot be an effort by one person, and I do not want it to further distract me from development.

1 Like

ok, Ive completed first pass of all factory modules … Im done for now :wink:

2 Likes

ok, Ive now added parameters, input/output etc to all my modules…

that means, the main ‘grafting’ is now done, for all factory and my modules.
(I spent most of yesterday on this, and another 2+ hours today… so its been quite a slog… things I do for you :wink: )

really now it’s up to the community to help improve this docs, and make them useful.


I’m currently working on SSP development projects, so I really don’t want to spend more time on this, esp. until I see that the community is finding them useful.

3 Likes

Thank you! I’m sure this will be useful to future new users looking for documentation.

1 Like

Thanks… great work… very helpful to have them
All one place…

2 Likes

My account got flagged after one post (ARP) regarding CI output.
Which btw is this * Clock Multiplier Out - the divided/multiplied clock created using the clock input, internally in the arpeggiator.

I’m not sure why, I’ve sent a ticket.
I’ll help with this if I can it’s a great idea.

if only we could print the WIKI in it’s totality :grin: :thinking:

On GitHub or here?
There’s nothing on GitHub to say anything was held etc, so it’s not related to this repo.

You can download the file as a repo, then with a bit of post processing turn it into a pdf with hyperlinks ( or print) …. But I’ll leave that for your homework.

I’ve done this for another project, so definitely possible.

It was on GitHub. I try to edit the wiki at the Cl output on the arp section, and I got the suspended account message.

yeah, its not from my side… its a GitHub thing… see this post , and this
they probably check some external database to look for suspicious accounts, and of course, these gets ‘false positives’ occasionally… perhaps new or un-used accounts are more prone.
as Ive been using GitHub for around 10 years, never had an issue…(didnt even know they flagged accounts!).

hopefully they can sort it out quickly… or if its an old unused account, you could create another?

edit: just to be clear to other reading this…
you do not need a GitHub account to read the wiki, its only for contributions back to .

Issue resolved… It was an overzealous bot :wink:

2 Likes

updated :

  • to include my new modules : VOST and MTTR.
  • to include Percussa PLY (polygon oscillator) module.
  • ‘getting started’ to point to new beta release.

note: for simplicity, the wiki will track the current release, and including active betas/early access.
basically, I need to publish the ‘new information’ , as this is when its most needed - but really dont want to start having caveats on which version we are talking about.
besides… you know you want to use the latest and greatest :wink:

if you have concerns using betas etc, then Id recommend getting another sdcard, one for ‘performance’ (aka stable) and the other for betas/new versions.