Linux Documentation

2004-09-15
2004-09-17
  • James E Lang

    James E Lang - 2004-09-15

    I've just been looking at the Wiki content for installing on various Linux systems. It looks to me like the SuSE and Mandrake documents are very near duplicates of each other. I opened the two documents in separate pages on my Opera browser and toggled back and forth between them to spot differences. The only differences I could find were these:

    The first line under "General" identifies the version of SuSE or Mandrake for which the documentation was written.

    Within the "RedHat comment block ..." I found a blank line inserted in the Mandrake version. This raises the first question: Is that blank line significant?

    The symbolic link to the /etc/init.d/popfile script from /usr/sbin/ is named rcpopfile in the SuSE version and it is named popfile-service in the Mandrake version. This raises the second question: Are these names significant? These names appear in the bullet items "Create a symbolic link to ..." and "Startup POPFile."

    The section "Configuring the mail client" deals with different mail clients for SuSE vs Mandrake. This raises a third question: Aren't all three of the mail client configurations available on both distros?

    My thought is that these two documents ought to be made into one with a link to a separate document for each of the mail clients. Of course this is not practical if either the blank line referenced in my first question or the symbolic link name referenced in my second question is significant.

    Am I way off base with this suggestion?

    --
    Jim

     
    • Scott Leighton

      Scott Leighton - 2004-09-16

      Each Linux distro has subtle differences. The SuSE one is written specifically to SuSE users, the Mandrake one to Mandrake users.

      I would say leave them as is.  Distros have different naming conventions for their startup scripts and different pre-packed mail setups. These two have been tailored to their respective distros by people who are using those distros (myself, for SuSE, and Sam for Mandrake) so we can be reasonably sure that the data is accurate.

      I think the users of those distros will appreciate having one place to look for their particular setup.

      Scott

       
      • Texas Fett

        Texas Fett - 2004-09-16

        I agree one place for each distro is better.  Currently the setups are very similar, but thats probably because SuSE and Mandrake are closely related.  Many other distros may be similar, but many are very different.

         
        • James E Lang

          James E Lang - 2004-09-17

          I only thought that since the Mandrake document appeared to have been created by the copy/paste method with a minimum of editing that the two documents could be combined into one.

          I am using pseudo tags in the following documentation examples to overcome shortcomings on these forums.

          The references to the symbolic link could be easily covered like this:

          <bullet> Create a symbolic link to the init.d service
          <indent> <bullet> SuSE
          ln -s /etc/init.d/popfile /usr/sbin/rcpopfile
          <indent> <bullet> Mandrake
          ln -s /etc/init.d/popfile /usr/sbin/popfile-service

          <bullet> Start POPFile
          <indent> <bullet> SuSE
          rcpopfile start
          <indent> <bullet> Mandrake
          popfile-service start

          If the Mandrake distro is not conducive to using Fetchmail then the link to a separate document for configuring Fetchmail in the "Configuring Specific Mail Clients" section would be similarly tagged.

          Of   course, if the blank line in the middle of the comment block of the script installed in init.d is truly significant my idea is a non starter.

          My point is that the effort to maintain two nearly identical documents is almost double that of maintaining a single document with the subtle differences noted. I've already seen that some of the documents are understandably not kept up to date.

          In any case the part of my suggestion that deals with the configuration of the mail client appears valid to me since there are already separate documents for configuring a variety of mail clients. A document for KMail and one for Fetchmail under the "Configuring Specific Mail Clients" section would be more consistant with the rest of the documentation than is burying this information in the SuSE and Mandrake documents. There are already similar documents for Pine and for Ximian both of which are Linux mail clients.

          I might add that the HowTos/Linux document which also shares the same init.d script is missing the added line in stop() that permits restart() to function correctly. This is just another example of documentation that relates to a common operation but that is not kept up to date.

          --
          Jim

           
          • Texas Fett

            Texas Fett - 2004-09-17

            The second one of these probably is just a cut and past of the other one, but like Scott and I said other verisons of Linux could be significantly different.

            And if someone makes a change to the SuSE that updates it for a new version of SuSE it may not match Mandrake.  Mandrake may make huge changes and not use /etc/init.d anymore.  Maybe to be more user friendly they more it to /startup/scripts or something.

            It is a pain to maintain two seperate documents, but unless you use both (which is very unlikely) you could be making a mess on the other Linux.

            >>init.d script is missing the added line in stop() that permits restart() to function correctly.<<

            If your talking about the modification I suggested of deleting the pid file then I think the reason its been left off is its not a really good solution.  Its probably better than what we had, but I hoped some Linux users check it out and see if it is a good idea or could be improved.  I don't use Linux much and only used that startup script when testing it out.  Since I don't get mail through my Linux machine I don't need POPFile running except when testing some new bug or feature.

             
          • Scott Leighton

            Scott Leighton - 2004-09-17

            I understand your points about maintenance and keeping things up to date, but I still firmly believe that separate documention for each distro that a user is willing to document for us is in the best interests of the userbase. The goal of perfect documentation is laudable, but I seriously doubt it is attainable.

            It's my personal bias speaking, and I acknowledge that. I hate it when I have to go digging around the docs to figure out how to get a package running on my distro, I strongly prefer having distro-specific instructions, it is just so much clearer and easier for the new *nix user who is struggling with information overload and distro confusion from the get go.

            Frankly, I would prefer RPM's be built for the major distros. I'd do it myself for SuSE if I had the knowledge, but I'm not there yet.

            Anyways, my 2 cents...

              Scott

             
    • James E Lang

      James E Lang - 2004-09-17

      Ok  ;-)

      --
      Jim

       

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks