Re: doc-central

2017-10-13 Thread Diane Trout
On Fri, 2017-10-13 at 08:41 +0100, Simon McVittie wrote:
> On Fri, 13 Oct 2017 at 08:13:08 +0800, Paul Wise wrote:
> > On Fri, Oct 13, 2017 at 3:27 AM, Diane Trout wrote:
> > 
> > > Being able to find all your documentation in one place would
> > > really be
> > > convenient.
> > 
> > I don't think doc-base/doc-central will ever be the answer to this
> > as
> > it is very specific to Debian and thus not available on other
> > distros.
> > Eventually the Freedesktop folks will come up with something
> > cross-distro and cross-desktop and we will have to replace doc-base
> > with it, just like we had to do with the Debian-specific menu
> > system.
> 
> ... unless someone from Debian with an interest in documentation goes
> upstream and comes up with something cross-distro, cross-desktop and
> suspiciously similar to doc-base. Relevant people to talk to would

FWIW rarian is the closest thing to a freedesktop documentation
standard. It derives from scrollkeeper, and I thought scroolkeeper was
originally from Debian.


> As far as I understand it, yelp and devhelp are separate apps as a
> deliberate design choice, because they have different audiences and
> requirements. Whether you agree with it or not, understanding the
> reasoning behind that design choice seems likely to be valuable.

My first guess is that separating them makes it easier to simplify
search. Users will find user docs and developers will find developer
docs, and they can't accidentally be confused.

Which makes me wonder a bit about all the sphinx docs where there's a
user chapter and then API docs.

Diane



Re: doc-central

2017-10-13 Thread Simon McVittie
On Fri, 13 Oct 2017 at 08:13:08 +0800, Paul Wise wrote:
> On Fri, Oct 13, 2017 at 3:27 AM, Diane Trout wrote:
> 
> > Being able to find all your documentation in one place would really be
> > convenient.
> 
> I don't think doc-base/doc-central will ever be the answer to this as
> it is very specific to Debian and thus not available on other distros.
> Eventually the Freedesktop folks will come up with something
> cross-distro and cross-desktop and we will have to replace doc-base
> with it, just like we had to do with the Debian-specific menu system.

... unless someone from Debian with an interest in documentation goes
upstream and comes up with something cross-distro, cross-desktop and
suspiciously similar to doc-base. Relevant people to talk to would
include the maintainers of GNOME's yelp (user-facing, usually-topic-based
help in Docbook or Mallard format, processed into HTML for viewing) and
devhelp (developer reference documentation in any format, processed into
HTML at build-time), and their equivalents in other upstream projects.

As far as I understand it, yelp and devhelp are separate apps as a
deliberate design choice, because they have different audiences and
requirements. Whether you agree with it or not, understanding the
reasoning behind that design choice seems likely to be valuable.

smcv