Proposed changed to documentation

[Allan Day]

Michael Hall <mhall119 at gmail.com> wrote:
> There isn't a list of changes, the sitemap is an effort to "reorganize and
> expand" what's already there.

The sitemap has to be translated into a series of changes at some
point though, doesn't it? I'm struggling to know how I'm supposed to
interpret the sitemap without having to do some detailed
cross-referencing.

> The reorganization is based on a developer's journey, assuming no prior
> knowledgge of flatpaks. ...

I think that's pretty much how we tried to structure the existing
documentation. The one exception is the 5 minute "hello world"
tutorial, which we wanted to keep on flatpak.org, as a lightweight
introduction. I'm not opposed to moving that to the developer docs,
but we'd have to figure out what, if anything, is going to replace it
on the website.

> Much of that already exists, but often it's not very thoroughly described.
> SDKs, for example, have only two sentences describing them. As an app
> developer who read through this the first time, it wasn't clear to me that
> the build steps happened *inside* the SDK's environment. It wasn't clear how
> the tools in that environment could be called, or how I could get a shell in
> that environment to see what was available. Something like that deserves
> it's own section, if not it's own page.

That's a great observation and sounds like a good change to have. If
you have details of other bits of missing information, it might be
useful for you to report them as issues.

> I based a lot of this on past experience designing the developer journey and
> sitemaps for Snapcraft and the Ubuntu SDK, what we learned from them about
> what works and what doesn't, and feedback we heard from developers as they
> learned to use them.

Good to know!

Allan