More examples and getting-started code demos needed

[warpfork]

Like it says on the tin.

Making an issue for this so we can put it on boards to remind ourselves there's work to be done here. However, there could be a lot of specific targets in this area, and I'm not sure I can enumerate them all immediately -- more issues may follow.

Some examples of room for improvement:

• some of our big end to end example code right now has package scoped variables in it -- which don't show up well as the godoc sites render examples, and also pass state between two separate examples, making them very hard to read and very fragile
• some of our big end to end example code has critical reliance on a side-effecting import -- also doesn't show up very well as the godoc sites render examples, so, problematic: frequently leads to users not seeing that critical bit, and being derailed for a while
• a lot of our example code is just plain boilerplate havy
• need more examples for how to use selectors
• need more examples for how to use traversal package in general
• need examples that show transcoding -- in as few SLOC as possible
• need more examples for creating dags (e.g. using LinkSystem -- repeatedly)
• need examples that show how to create a content-addressable storage system on disk
• etc

[drgomesp]

Would be nice to have an example of how to create a sort of DAGService implementation using go-ipld-prime, if that's even applicable anymore, of course.

[rvagg]

@drgomesp one of the difficulties with that API is that it's primarily built around the dag-pb codec, which only manages lists of links and an optional byte array. So it's relatively straightforward to model an API that "builds a DAG" by just adding and removing CIDs. Because go-ipld-prime is not tied strictly to a codec, just arbirary "nodes" in a graph that may or may not involve links, you have to bring some strong opinions about the shape of the data structure to do it.

But maybe such an example makes sense if it's strictly modelled on the dag-pb structure and can therefore be output through the dag-pb codec. Or maybe it could demonstrate a more modern form that uses dag-cbor and a HAMT. I've been working toward some "collections" style work for IPLD that are essentially large managed collections of links, with some additional nice features, maybe that'll end up being a useful example when I finally get something worth showing.. although I'm primarily working on JS with it first, so a Go form may be even more delayed.