Docs for snapcraft

[Didier Roche]

Le 01/06/2016 01:25, Sergio Schvezov a écrit :
> El 31/05/16 a las 07:41, Mark Shuttleworth escribió:
>> Hi folks
> Hi there.
>
> I'm going to break the ice here or try to.

Hey,
>
>> It's great to see the level of interest in making snaps! I've been
>> tracking comments and a lot of people seem to be stuck on snapcraft, so
>> I think we can put some effort into improving those docs.
> We landed a change which will come in 2.10 which on `snapcraft init`
> prepares something you can snap right away. I've been on the crossroads
> on this one but it figures that someone doing `snapcraft init` is just
> getting started with the tool. So now you can
>
>     $ snapcraft init
>     $ snapcraft
>
> And get a snap right away. I want to make this more guided as we move
> along (gamification).
>
> It is still a template to the keen eye, so it is still of use to someone
> in the know how wanting to ramp up a new project.
>
>> But I wondered if we shouldn't instead focus up front on explaining the
>> snap format itself. That way, people could make snaps manually
>> initially, then switch to using the tools they like best for making the
>> snap.
> What to expect of a snap and how it integrates with the rest of the
> system would be really ideal. I would paint it with user stories ("I
> write desktop apps ...", "I work on embedded systems over i2c..", etc.)
> so we don't go into length about technical details that are not relevant
> to some people. Yes everyone uses `interfaces`, but introducing the
> concept at the right time makes things easier to grasp because it
> matters to the persons use case at that time.

I agree with Sergio that we should concentrate on the tools people will
spend the most time with at the main focus, and build our getting
started story around it.
Developers focus on tasks, like "I want to build an YYY app", and having
this as clear titles in the documentation, learning notions steps by
steps and complexifying the use case (still reusing a large part of
familiar concepts, learnt in previous sections) is the key to not have
people lost in the journey.

The gamification and instant gratification is the compelling case for this:
1. do this
2. run and enjoy
3. explain the new notion we just introduced
4. goto 1

>
>> Personally I think snapcraft is amazing, but it does create an extra
>> layer of abstraction to push through, which may be confusing to someone
>> just starting out.
>>
>> Thoughts?
> My thoughts are biased towards trying to use snapcraft for everything
> but we should not block on people wanting to do whatever they want
> during their creative process.

Of course, explaining the base concept (file system and such) is
important, but that can happen once we have 3-4 success of the virtuous
loop I explained above and having the base concepts nicely shaped in
developer's head.
Then, we can introduce a bug for instance as the next step, and see how
to debug/inspect it. This is when the snapcraft lifecycle concept, and
the snap/ directory can be introduced, exploring this way the snap (and
not snapcraft) concepts like meta/snap.yaml, wrapper, and file system…

Does this make sense?
Didier