Proposed changed to documentation

[Michael Hall]

There isn't a list of changes, the sitemap is an effort to "reorganize 
and expand" what's already there.

The reorganization is based on a developer's journey, assuming no prior 
knowledgge of flatpaks. Each top-level section represents a milestone 
in that journey, from getting the flatpak tools, to building and 
finally publishing their flatpak. Inside those are the information and 
steps needed to reach each milestone, in the order they are going to be 
needed. So Building starts with an explanation of Runtimes & SDKs, then 
introduced flatpak-builder, modules and buildsystems, then exported 
files, then testing what should be a working flatpak at that point, and 
finally offers extensions and localization to finish it up.

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.

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.

--
Michael Hall
mhall119 at gmail.com

On Wed, Dec 13, 2017 at 7:09 AM, Allan Day <aday at gnome.org> wrote:
> Michael Hall <mhall119 at gmail.com> wrote:
> ...
>>  Recently I've been looking at the developer experience around 
>> Flatpak, and
>>  especially the documentation available, from the perspective of an 
>> app
>>  developer looking to make his first Flatpak. ...
> 
> Thanks for doing this, Michael! I agree that the docs could probably
> do with a round of updates.
> 
>>  ... I wanted to make sure that this sitemap has approval from
>>  all the necessary people, and that pull requests to implement it 
>> would be
>>  accepted. If I can get that buy-in, I will finish fleshing out the 
>> rest of
>>  the details and then work on finding people who can help write the 
>> missing
>>  pieces.
> 
> TingPing is the one who's accepting pull requests at the moment, so
> he's probably the most important person for you to speak to.
> 
>>  Proposed sitemap:
>>  
>> https://github.com/flatpak/flatpak/wiki/Documentation-Sitemap-proposal
> 
> It's difficult to tell exactly what changes are described by the site
> map. It would be helpful if you could provide a list of the changes
> that you want to make, along with the reasoning behind each one. It
> doesn't have to be super detailed...
> 
> Allan