Sniff is a "Scratch-like" programming language that's designed to help Scratchers move gently from Scratch to more conventional languages. They can start writing programs, without having to learn a new language because Sniff is based on Scratch. They learn a little more about variables, compiling, syntax errors (!), and they can have fun controlling real hardware while they're doing it.

Wednesday, 23 November 2016

Sniff Documentation-fest

Lets be honest... no one likes writing documentation, and the Sniff docs haven't been the best. It's just more fun writing code than writing it up. We'd claim that all the information you need it there, either here on the blog, or in the examples folder but as the blog has got bigger (great - more resources and ideas!) its increasingly harder to find older posts. I'll admit I've googled my own posts to try and find instructions for a project I developed months ago.

While the examples folder is still the goto-place for code to get you started, the last few weeks have been spent trying to put together something more tangible, so you've a solid base of reference material you can work from. 

In fact we've always had a manual... you did read the manual right? Most of it was written way back when Sniff was very new. It's in the Sniff/docs folder when you download Sniff. We've now given it a bit of an overhaul, adding a few extra chapters to the tutorial section, updating the reference section, and adding an index of blocks, so you can look up "blocks" in alphabetical order. While the updated version will still be in the docs folder for download the pdf of the latest version is in the new online docs folder.

In addition we've updated the Device docs. "Devices" are external code to talk to specific hardware, so there are quite a lot of these (currently 145, though some of those are interdependent), and keeping track of how to use each device can be quite hard. Again there were some docs for a couple of the Devices: Filesystem and Sprite, as these are two of the more complex Devices with many commands, but now we've added documents for some of the simpler devices on the basis that these are the ones you'll encounter first, and need the most help with. They should be suitable for printing out, and keeping a few copies around when you're working with a particular device.

For each documented device, there's a page on the hardware (of appropriate), a page defining the Variables used, and then a list of all the commands that the device recognise. For each method, the variables that it uses as parameters are shown in a table, with a brief statement on their meaning. Finally there's an example.

We're still refining the format and the documentation only exists for a small subset of the available devices, but hopefully by establishing a standard format for documenting devices, we can do better in future (and at least document new devices better).

Currently there are documents for DHT11/DHT22, DS18b20, text LCD's, the Motor Controller shield, NeoPixels, IR Receiver for use with Arduino, and for Hosted systems there's Filesystem, Sprites, Flotilla and Window. There's also a generic DisplayDevices which applies to all bitmapped screens.

You can get The Docs online now, and we'll be including them as PDF's in future distributions of Sniff. The Sniff distribution will also include the LaTeX source for the main manual, and Pages files for the Devices so you can edit them (If you're PC based, then you can still edit pages on iCloud).

No comments:

Post a Comment