Proposed changed to documentation

[Michael Hall]

--
Michael Hall
mhall119 at gmail.com

On Thu, Dec 7, 2017 at 11:01 PM, Markus Richter 
<semanticdesign at mailbox.org> wrote:
> On Thu, 2017-12-07 at 11:41 -0500, Michael Hall wrote:
>> <snip>
> 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.
> 

There shouldn't be docs in the wiki. The links in the sitemap point to 
where there is already documentation on that topic, not to where it 
should live in the end. Everything identified in the sitemap should, 
ideally, be on docs.flatpak.org

> ## 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.
> 

Agreed. The focus of this proposal is only on developers making flatpak 
packages, not users who are installing/updating them.

I'm skipping the rest of the email because I don't know enough of 
translations workflows to offer any useful feedback there. But I am 
willing to do whatever it necessary to support translators.

> 
> 
> ## 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.
> 

Hopefully there will be little or no rewriting necessary for this 
proposal. I believe all of the existing documentation (and it's 
translations) can still be used, just reorganized and expanded on. 
That's why I've been linking to existing documentation in the sitemap, 
so that it will be reused.

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

Same :)