Blog Post

Docunification

As a member of both the Ubuntu Documentation Project and the KDE Documentation Project, one thing is clear, our current state of system help isn’t the greatest. An initiative that the GNOME project has looked at taking on (for the greater part of the past 3 years) is called Project Mallard. There are some things in this project that I like and dislike, however one thing is clear, they understand the inefficiency of their current system and know it needs to be fixed. KDE is realizing this same exact thing and know we need to fix it, but figuring out how to do so correctly, isn’t the easiest thing.

One thing that GNOME, KDE, and others have worked hard to do is collaborate with Freedesktop.org specifications on many levels. Maybe it is time we look at continuing this excellence, but this time add documentation to the menu. How many of you GNOME users love using Amarok or another KDE application, but hate the fact that KHelpCenter is installed just so you can view the help documentation? Granted a lot of this has been fixed by just recommending KHelpCenter in the packages, but this doesn’t fix the issue, because now you have a .docbook file to read, and guess what, Yelp isn’t going to open it cleanly for you, or at least the last time I looked at Yelp it didn’t. Or you have KDE and want to open up the .xml file with KHelpCenter, but it just doesn’t work correctly. I think if we were to unify documentation we could move toward the goal of world domination 🙂

Would working closely together help fix our issues, would this be a good thing? What would be the “best” way to move forward?

This entry was posted in Development and tagged , , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.
  • Jonas

    Yes! Excellent idea! Seriously.

  • GM

    I think your best option is to add in features to both of the help doc readers to read a standardized xml format worked on and agreed upon by both of you and then begin to move your current documents to this xml spec and phase the other one out and eventually drop the code for reading them to just be in legacy versions. Having recently (last 6 months or so, late i suppose) come to see xml properly and realise how wonderful it can be in being universal in that the same docs can be read with any program once you understand its specific structure, it is most likely the most obvious choice. This way then, the two readers or even other that people may make to be more lightweight or even web based ones to run on their system can all read all of the documentation. You may then also be able to release a program or add in a document writing feature to the help programs for developers to easily write their own compatible documentation for their own apps.

  • rawsausage

    Make the software actually usable. Then you don’t have to waste time with documentation.

  • Michael S. Olsen

    I agree that a HUGE problem throughout the Unix/Linux communities is the excessive array of documentation formats (man, docbooks, TeXT, etc.). The difficulty in fixing the situation lies not at the team or individual level, but at the Academic and Corporate levels. Several of these format were built specifically for a particular institution, and because of the sheer volume of data/info they have provided, has become a defacto standard. Personally, I would love to see all documentation formatted into XML so that it could be easily read with a broad array of readers and reduce the disk space used. Perhaps the best method of achieving this is to take the matter to the producers of the various distros. If they would consent to a single standard, then the various middle/software “vendors” would more likely move to the same standard. The other solution, would be to appeal to a standards organization (e.g. IEEE) to set guideline to define the type of data/info that should be included in a particular format. This would allow end users, researchers and others to more readily find data specific to their needs. Either solution will require a serious conference of those groups publishing and using the data to make such a solution viable. Let us hope that key leaders of those groups are listening.

  • Don AKA Seeker

    As a user I think it would be a definite boost in consistency and usability if there were a standardized format and location for documentation in general so users could choose the default help application they want to view documentation with.

    If LSB compliant software is supposed to keep everything not provided by the LSB base within it’s own application dire, it would be nice if documentation for those went into a specific place within that self contained directory, so ISVs could have a generic standardized way to tell the help viewer ‘I’m a 3rd party application’ and the help viewer would then automatically know from the location of the application directory where to look for the documentation when the user chooses to view the documentation/help from inside the application.

    Later, Seeker

  • >Would working closely together help fix our issues, would this be a good thing?
    Certainly.
    >What would be the “best” way to move forward?
    Standardising on a single documentation/help format is the way to go *in the long term*, preferably as an opendesktop standard.
    Better support for the various formats in use could be a good short to mid term solution.

    Just my 2 cents. :]

  • Michael “Cool” Howell

    @rawsausage: Who are you addressing exactly: KDE specifically, GNOME specifically, the free desktop initiative in general, the computing world in general (basically every widely used computer program, be it Konqueror, Nautilus, Windows Media Player, or Safari has documentation of some form), or specifically Richard Johnson.

    post: One solution I can think of is to use a very, very simple solution: .desktop.

    [Desktop Entry]
    Name=GApp
    Help=http://path/to/online/docs.html

    [Desktop Entry]
    Name=KApp
    Help=file://path/to/offline/docs.docbook

    Under KDE, KParts would take care of format support (isn’t KHelpCenter already KPart-based?). Under GNOME, I think they could use mimetypes to simply launch a native program for it. It would allow for Nano’s short-term solution (support a few different formats), as well as his long-term one (a standard format).

  • Sure, lets cede some more functionality to design-by-committee. Wake me when its over and give me the subset of things we can still do.

  • oliver

    This is a great idea! One question, though: what’s the scope of this unification? Is this only meant for the help files written specifically for KDE and Gnome GUI apps, or does it also include things like manpages, info pages, Devhelp files etc as well? (Personally I would think that focusing on the application help files would be best for a start, to keep the project manageable, but maybe you have already thought this through?)

  • Gonzalo

    The standard document format already exists (ODF). We just have to be able to create a light reader around it for help documentation. That would make it so much easier to have apps from GNOME and KDE living together under one happy roof.

  • Don AKA Seeker

    “One question, though: what’s the scope of this unification? Is this only meant for the help files written specifically for KDE and Gnome GUI apps, or does it also include things like manpages, info pages, Devhelp files etc as well?”

    Don’t know about Info and Devhelp pages, but man pages already see to follow some kind of standard and Khelp and Yelp already are both able to show them to you. Info pages also seem to be a set standard that functionality could be included for.

    “Sure, lets cede some more functionality to design-by-committee. Wake me when its over and give me the subset of things we can still do.”

    I can’t imagine what would be desired in a help system that would be hampered by a preference for adherencing to a standardized help file format and mechanism for triggering the display of the help files from within an application. It doesn’t seem to me like help files need to be all that complex. Some hyperlinking, and index, text, pictures, audio, video, and….?

    Later, Seeker

  • Hi.
    I wonder if it would be possible to have a software object called “desktop” with some classes and methods. And this object is writen in xml and posted as a native xml database, as sedna, on the Operating System.

    And the desktop object would be writen in OCAMLDUCE (you can compile it).

    You know, there is no such thing “free launch” and “object oriented programming” (or modeling).
    There is no Object Oriented Operating System, so, the OO software objects does not exist inside an Operating System which does no understand objects.
    Remeber Dr. Quantum on the flat planet?

    What is the difference between KDE and GNOME?
    Applications, programs, design(er), windows … what?
    Why do you have unificate everything, at all?
    “help” could be an object too: with its own classes, methods…
    ” Michael S. Olsen (15:06:22) :
    (Using Konqueror Konqueror 4.0 on SuSE Linux SuSE Linux)
    I agree that a HUGE problem throughout the Unix/Linux communities is the excessive array of documentation formats (man, docbooks, TeXT, etc.).”
    If EVERYTHING is writen in xml what is the difference if there is 100 types of files? Everything can be re-writen in xml, so, the problem is not a 100 types of files, but how many of those files ARE NOT writen (or re-writen) in xml.

    About the Linux issue versus the windows issue:
    Linux is not a REPLACEMENT as all the Free Source SofteSware are not REPLACEMENT for proprietary software.
    You see, OpenSource World is not the same as Proprietary World:
    OpenSource#Proprietary and World = World.
    There is no way to prove one is better than the other, since the problem is if you have got your computer WITH one or another: your going to be user of the system was installed on the computer you used since the first day.

    The fight KDE against GNOME or others is a lost-lost fight.

    It does not matter if you write a docbook or xml or any other type of help, man file. The issue is if you can read them all whatever program you are using.

    You can see the loose-loose fight on package management programs: rpm, deb, etc.
    There is no Linux Distros out there, that is a package management fight.
    I wonder if would be better if there was no package management and you can install whatever you want on a simple way – take a look at GoboLinux.

    For example, what you call “kernel”?

    The source code of that portion of software that goes to the RAM and make everythin else work?
    And which is the compiler needed to compile the kernel? And the text editor to write the kernel code? And the compiler code? And what is the language you used to write all those programs?
    Well, I think that EVERYTHING you NEED to put a kernel together IS the kernel.
    So, if you install a kernel on a Linux Distro, I think you should install everything you need to write and build the kernel as a kernel package, as a whole.
    And, yes, you will have to install another copy of those packages the USER will need to build the DISTRO.
    Now you have a kernel environment separated of the distro, and you have a distro, not a package management system with some programs AND a kernel.

    I think I feel the same when I see Microsoft and Linux Distros out there pulling their wishes and dreams over everyone else.

    Yes, I know, it is open and I CAN do it myself.

    Linux has some quite big problems with its engineering before to become a really operating system and people use it.

    I know a bit of Linux and I can use it.
    I think the producers should think seriously about freezing the race for one year and finish the job.

    You see, MAC is nix, now.

  • Subscribe to nixternal.com

     Subscribe in a reader

    Or, subscribe via email:
    Enter your email address:

  • Archives


semidetached
semidetached
semidetached
semidetached
%d bloggers like this: