Xfce Documentation Project

[Nick Schermer]

On Sun, Oct 24, 2010 at 11:39 AM, Jannis Pohlmann <jannis at xfce.org> wrote:
>
> On Sun, 24 Oct 2010 00:55:03 +0200
> Nick Schermer <nickschermer at gmail.com> wrote:
>
>> * We empty the xfce4-docs repo and create branches like
>> <project>-<branch>, for example xfce4-panel-master. Inside the branch
>> we add the doc files + images + Makefiles.
>> Right now the documentation translations are also located in this
>> folder, but we can move those to handle all the translations in the
>> (for example) xfce4-panel modules or in xfce4-docs (transifex commits
>> in xfce4-docs).
>> I think the latter is somewhat better since then translators always
>> see the latest docs changes, this also means one xfce4-docs module in
>> transifex with multiple components for each project, projects can use
>> those components in releases for a better overview... ok... OT.
>
> Branches are not there for alternative content but for variations of
> the same content. So, while I can see how separate components would be
> nice in Tx, I don't think we should violate branches for that. One
> folder for each repository that needs documentation is better. And only
> one branch for now: master.

Tx is so flexible i can setup separated components for different po
folders in 1 branch too (like xfce4-panel has with master and
master-docs), so that's not an issue. However, the submodules in other
projects are important. Personally I don't want doc writers to have
write access in other modules, in fact even some of the core
developers are not allowed to write in every module of core, so why
should doc writers.

Apart from the fact that we abuse branches a bit (not IMHO; git
supports empty branches for code rewrites), it gives us the most
flexibility: we can use the branches for submodules in other git
clones and we could create 1 doc tarball by including the branches in
the master branch of the xfce4-doc module (maybe some disto want this
or it makes things easier for doc writers).

The doc tools can also be moved in xfce4-dev-tools, which might
actually be a best place for them, but a folder in xfce4-docs/master
is fine too (noinst_scripts maybe) for a start until we have some
decent scripts.

So, although I agree with you branches shouldn't be used in core
modules (panel, thunar etc) like I've suggested for xfce4-docs, I
think it's a small hitch we can overcome with all the good stuff it
will give us when we have a maintained documentation module (after
many... many... years).

Nick