Xfce Documentation Project

[Jannis Pohlmann]

Hey,

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.

> * A "documentation-tools" branch for scripts doc writers can install
> on their system to update po files, validate stuff, build
> mallard/docbook html to viewing the result. Might also be useful for
> translations since I've seen a lot of translations that result in
> invalid xml when merging with xml2po.

Again, this is nothing for a separate branch but for a subdirectory
inside the repository.

> * The master branch and (eventually the xfce-4.x branches) for the
> xfce users guide, which means moving this out of xfce-utils[1]. We can
> release this as a new module for the global xfce documentation.

True, a separate tarball for the user-guide and global documentation
sounds good.
 
> * With the setup above we can work with git submodules[2], so
> developers can pull the latest docs from the xfce4-docs repo whenever
> they want and people working on documentation cannot touch the source
> code in core.

Sounds good, too, although of course this will not be as easy if we use
folders instead of branches, as I suggested. Using branches in this
context is really bad IMHO.

So, as an alternative to your suggestion, we could also use xfce4-docs
for the global documentation and documentation tools only and create an
xfce-docs git group that has access to all repositories, so we don't
need a centralized repository for the contents.

> * Setup git access for Robert, Jim, the core devs and all the people
> out there to work in the documentation.

Sure.

> [1] I'd love to get rid if this module some day. Xfrun can be migrated
> in xfce4-appfinder (on my 4.10 TODO list) and the other scripts can
> move in more suitable places or are already obsolete. However not
> suitable for discussing this right now.

Yeah. xinitrc, startxfce4 can be moved to xfce4-session. I guess we'll
find a better place for everything else as well.

> [2] Submodules can only work with branches (well a pointer to a
> commit), not cd into a directory inside a tree.

Yep, that's a problem with my suggestion. If we include the entire
xfce4-docs master branch as a local git submodule in all projects with
docs, we could maybe design the makefiles so that only the required
directories are actually *packaged*. Dunno.

Generally, I'd be happy to see this moved forward and if everyone
thinks branches are a good idea, I don't want to stop you from making
progress.

  - Jannis
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: not available
URL: <http://mail.xfce.org/pipermail/xfce4-dev/attachments/20101024/ff7ba945/attachment.pgp>