Improving Flatpak documentation

[Allan Day]

Hey Jorge!

Jorge García <jgarciao at gmail.com> wrote:
...

> Below you will find a quick list of places where you can actually find
> useful flatpak documentation. As you will see, the docs are in many
> different places (main site, flatpak's github wikis, some personal blogs,
> ...).
>

I don't think it's necessarily a bad thing to have docs in different
places, depending on the audience. For example, the split between the docs
on the website and the wiki makes sense to me, since the stuff on the wiki
isn't intended for users or for normal application authors. Likewise, most
of the pages on the website, like the ones that are aimed at end users and
testers, seem fine.

I also don't think it's necessarily an issue to have material initially
appear in personal blogs and then get moved over to other more permanent
locations. This is what happened with the developer page [1] on the website
- this was basically a rewrite of Alex's blog posts. However, those blog
posts should maybe have a warning added to them, to indicate that they are
outdated and that people should use the official documentation instead.


> Some information is duplicated and some is also outdated.
>

The documentation being outdated can only be fixed by updating the
documentation. :) There's a list of documentation issues filed against the
website that anyone can tackle today [2]. I am conscious that we are
somewhat behind in this area and that the website needs updates in a few
areas. It's been on my mind for a while that we should collectively spend a
bit of time on this.


> I propose to improve the main flatpak website adding a  documentation
> section, something like Angular's website
> <https://angular.io/docs/ts/latest/>, or Ionic Framework
> <https://ionicframework.com/docs/v2/> or create a manual at readthedocs
> like OStree. <https://ostree.readthedocs.io/en/latest/> (some of the
> information in flatpak's wiki is in Markdown already so most of the effort
> won't be wasted)
>
> I can help setting up the things (readthedocs, jekyll, ...) and organizing
> a little bit the docs, but I would like to have some help (I'm not a native
> English speaker)
>
> What do you think?
>

As time goes on it is likely that we will need a more advanced method for
hosting and organisatiing the developer docs [1]. Are we at the point where
we need to do that? I'm not sure.

Since there will likely need to be documentation for Flathub, it would be
good to include that in our plans. Perhaps we want a separate docs site
that covers both Flatpak and Flathub (like docs.flatpak.org)?

Thanks for bringing this up - it's definitely a conversation we needed to
have at some point.

Allan

[1] http://flatpak.org/developer.html
[2] https://github.com/flatpak/flatpak.github.io/issues
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/flatpak/attachments/20161123/ccb2627c/attachment.html>