Proposed changed to documentation

[Michael Hall]

Yes, my next task is to break each of these pages down into a list of 
sections and bullet points that they should cover to give a kind of 
scaffoling for documentation writers to fill out. Some of that will be 
pre-populated with documentation that already exists, and then we'll 
see what parts need new documentation written for them. But I wanted to 
make sure there was general agreement on the overall structure before I 
invest too much time in the details.

I planned on filing issues for each of these detailed sections so we 
can track the work being done on each one.
--
Michael Hall
mhall119 at gmail.com

On Wed, Dec 13, 2017 at 12:07 PM, Allan Day <aday at gnome.org> wrote:
> 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