Xfce Documentation Project

[Jim Campbell]

Hi All,

On Sun, Oct 24, 2010 at 5:18 AM, Nick Schermer <nickschermer at gmail.com>wrote:

> 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
> _______________________________________________
> Xfce4-dev mailing list
> Xfce4-dev at xfce.org
> http://foo-projects.org/mailman/listinfo/xfce4-dev
>

I know that the git stuff would need to be sorted out, but we could always
use gitorious until that gets settled.  Some time ago I created an xfce-docs
project repository in gitorious, and placed my xfce4-screenshooter docs as a
subproject there. (I filed a bug in the xfce bugzilla about the
screenshooter docs, too.)

One good thing about starting now is that there are more examples of Mallard
docs out there that can provide a good starting point for those who haven't
used Mallard before.  Currently, there's Mallard-based help for Empathy,
Evince, Banshee, and Tomboy. Docs are in-progress for Rythmbox and gedit
(links below).

Note that the GNOME doc team is updating their user guide in Mallard now,
and I think it would be good to piggy-back off of what they are doing.  I
mean this in the sense that the GNOME team is laying out help topics that
would likely be relevant starting points for anyone writing Xfce help, too.
Where possible (Xfce 4.8 will be a lot like GNOME-3, right?) we could look
to contribute back to GNOME, too (i.e., let them know what topics might be
easily portable to their help).

Here's some links / git commands to get the doc samples:
Gnome user help: http://gitorious.org/+gnome-documentation
Empathy: git clone git://git.gnome.org/empathy  (help is in empathy/help/C )
gedit: http://gitorious.org/gedit-docs
Xfce-docs: http://gitorious.org/xfce-docs

The easiest way to view the help is to have yelp installed.  You just
navigate to a directory just outside of the folder where the docs are
stored, and do (for example) "yelp gedit-docs/". Of course, the help can be
output to HTML, too, thus avoiding the need for yelp.

Jim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.xfce.org/pipermail/xfce4-dev/attachments/20101024/36bb4753/attachment.html>