Proposed changed to documentation

Fri Dec 8 04:01:35 UTC 2017

On Thu, 2017-12-07 at 11:41 -0500, Michael Hall wrote:
> Hello everyone,
> 
> 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. I
> found that, while there is a lot of documentation written, it's not
> easy to follow and often doesn't give enough information for me to
> fully understand how Flatpak works.
> 
> So, to try and improve this, I've put together a sitemap (link below)
> for documentation that I think will lead to a better developer
> experience, and ultimately more Flatpaks. This is a high-level view
> of the site structure and navigation, I will fill each section in
> with more specific information needs. But first 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.
> 
> Proposed sitemap: https://github.com/flatpak/flatpak/wiki/Documentati
> on-Sitemap-proposal
> 
> I wil be able to commit some of my work time at Endless to this work,
> but I don't have the knowledge or skills to write the documentation
> itself. I can contribute to planning, editing, and organizing the
> pull requests though. Nuritzi and I will see if GNOME can allocate
> funds to contract a technical writer, and if not I'll work on
> recruiting volunteers to get it done.
> --
> Michael Hall
> mhall119 at gmail.com
> _______________________________________________
> Flatpak mailing list
> Flatpak at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/flatpak

And could somebody think of the poor translators? :)

I really appreciate well structured content, but i would like to take
the opportunity to mention some issues concerning the translations.

# Scattered Content

## Wiki versus Dev Docs
I have asked this myself before, but i had no time to evaluate this
closer. Now in the new sitemap there are references to the wiki. This
means the content of the wiki and the docs differ indeed and i don't
see any sense in this – except confusing people and build redundant
data next to this.

## Flatpak Docs for End users versus Flatpak Dev Docs
Some topics should be of interest for both groups (as seen in the site
map references). Maybe there is more that would be of interest for both
groups and could be reused and has not to be written & translated
again.

## 3 Translations for Flatpak Dev Docs versus Zero for End users
If the user base is not following you, you can develop as much as you
are happy – they don't get it in their minds. How many articles in my
own language explain this concept? If people try to understand what
they should use, they get an english landing page or they can read
(now) the dev docs in their language. Where is the error?

How to solve?

## Translators want to translate, not to develop
When i started to translate the Flatpak Dev Docs, there was also a
request from my side to do this on Zanata (pushed by Jean-Baptiste
Holcroft). Right now, i am a little bit ambivalent about this platform.
But this is the choice for translations concerning Fedora. We could
discuss now if Flatpak is more freedesktop or GNOME (where the software
localization is done), but i really don't want to fight with git and
this is surely not only my concern.

Some thoughts:

### Zanata
Couldn't you throw the docs on Zanata, eventually with support from the
translation team? And every modification regarding the docs would get a
new version number there? 

#### Transtats
Transtats is also on its way, maybe this would help to get everything a
little bit more coordinated with less afford in the future.

#### Translation Memory
Next to this, we need the translation memory, better now than later.
This would help a lot if the docs are rewritten. And it would help to
translate the docs for the end users with much less effort. I don't
think i could take my TMS from Lingotek and transfer it to Zanata. ^^

#### Glossaries
At the moment i am using one for my own purposes on Lingotek (as my
CAT-Tool). But Zanata has one for the Fedora-stuff and hopefully we
could extend this or integrate a second one for some projects …
whatever. But at the moment nothing is consistent. And there are other
projects connected to Flatpak.

This is another point:

## Benefit for connected projects
Maybe some i could mention now
* Project Atomic, Atomic Workstation
* OSTRee, RPM-OSTree
* Flatpak, Flat Hub
* Modularity, Factory 2.0
* …

If we do some translations and we don't use the same glossary for every
project and extend it and we don't make use of a TMS, then everybody is
cooking his own cakes. And it's a waste of time, every translator has
to start new and build his own terminology and own TM. But all this
projects are connected with each other. This is why we should use
Zanata for the translation: Consistency. Efficiency.

## Review swaps
Translators are not necessarily developers. #menot

What i can do is
* ask myself same question as the user
* do some heavy research
* build the terminology in my language
* pay attention to causality
* explain it to me and to an imaginary user

But this makes me not an expert. Everything is brand new (Flatpak,
Modularity, Atomic WS, OSTRee). The truth is: We have to build the
terminology for other languages. We can abstract some parts from git or
from given container-technology. But it is new. it has to be discussed
(wording, meaning, context). Somebody who is experienced with git could
understand some parts of Flatpak/OSTree and do a review of the
translation in the specific language. It would be easier to swap
reviews if they would be on a centralized place. Don't you think so?
And wouldn't you think this is necessary? The Docs are the reference.
If magazines write articles. What will they use to find the words to
explain it to a broader audience? To be honest this is one of the
reasons why i started to translate this stuff – i had a lack of words
to describe everything. Not enough articles as reference in our
language right now.

## Conclusion
And when you still ask, why is he writing so much. he is nobody … Well
, i have this situation with the translation for Modularity right now.
Pull request 10 days ago, no reaction, but new modifications of the
docs and now i am reading this: Rewrite of the fresh translated Flatpak
docs (from PR to published: one month). Generally I like the new
concept for the docs. But my point is, everybody is ignoring the given
infrastructure for translations and also an offer to support the set up
there. It is good to learn the basics of git, but i would prefer
collaboration tools for translations like Zanata or Transifex.

Having said this, i am a big fan boy of everybody here and it is nice
to learn so much new here.

-- 
Markus Richter | Semantic Design
Workbench for technical articles
[SaaS|FOSS]
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: This is a digitally signed message part
URL: <https://lists.freedesktop.org/archives/flatpak/attachments/20171208/4bfd869f/attachment.sig>