The Community Forums

Interact with an entire community of cPanel & WHM users!
  1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

Updates to cPanel Documentation

Discussion in 'General Discussion' started by Joshfrom, Jun 3, 2003.

  1. Joshfrom

    Joshfrom Well-Known Member

    Joined:
    Jun 3, 2003
    Messages:
    157
    Likes Received:
    0
    Trophy Points:
    16
    Location:
    White Haven, PA, US
    I am a new employee that has been brought on here at cPanel to take care of a number of projects in the company. One of my first projects will be to simplify and standardize the documentation for both cPanel and WHM.

    I've got a number of ideas already, but I would welcome any input that you have to make the documentation better. You can reply to this thread, email me at josh@cpanel.net or AIM me at cpaneljosh

    Joshua Shaffer
    Technical Liason - cPanel Inc
    josh@cpanel.net

    cPanel.net Support Ticket Number:
     
  2. ddent

    ddent Member

    Joined:
    Apr 8, 2003
    Messages:
    5
    Likes Received:
    0
    Trophy Points:
    1
    Wow! Docs!

    Here are my two wishes:

    1) The documentation shouldn't simply restate what the option name is with a different sentence structure. It should actually explain what the option does, why you might/might not want it, etc.
    2) Document more than just a list of options. There are lots of things I had to figure out just by poking around the system. I don't think that's a good thing...

    cPanel.net Support Ticket Number:
     
  3. Silverado

    Silverado Well-Known Member

    Joined:
    Mar 19, 2003
    Messages:
    154
    Likes Received:
    0
    Trophy Points:
    16
    Location:
    Backyard - Poolside
    It might be a good idea to flag certain features with a "skill" level as well. I no longer allow my reseller the options to edit DNS zones because a few of them "played with it" then screwed up their clients domains.

    I completely agree with ddent's first request. We don't need a rehash of wording regarding what the features do and do not do.

    cPanel.net Support Ticket Number:
     
  4. rbmatt

    rbmatt Well-Known Member

    Joined:
    Oct 21, 2002
    Messages:
    212
    Likes Received:
    0
    Trophy Points:
    16
    It would be great if the end user version was easily "brandable". Meaning we can put in server names and our logos.
    f/e in the ftp section, it would say use server ourservername.com

    cPanel.net Support Ticket Number:
     
  5. trakwebster

    trakwebster Well-Known Member

    Joined:
    Jan 29, 2003
    Messages:
    145
    Likes Received:
    0
    Trophy Points:
    16
    I have had to write a lot of documentation (and clean things up when the documentation was inadequate). Here are the things I've found that make documentation useful to users.

    First, what is 'Useful to users'? It means the guy can read it, figure out what to do, and avoid confusion.

    Let's take that last one first. If you let the guy become confused, then from that point on he probably will obtain no benefit from the rest of the section, because he's peering through a confusion.


    So step one is to avoid creating confusions. The easiest way to avoid confustions is to never, ever, ever use a word that has no definition. As soon as a guy reads a sentence containing a mystery word, the sentence means nothing, the paragraph is questionable, and the section will probably not be something he'll be able to use.

    This would apply to acronyms as well. So suggestion #1 is to avoid using mystery words where you can, and to define tech words and acronyms when they need to be used.

    Next, give each section a 'Purpose' or 'Overview' sentence at the beginning. Imagine opening a tool box on a spaceship and it contains tools you've never seen. The very first thing that would be useful to know would be "What is this tool used for?"

    A listing of what to type in is the least useful type of documentation, though it is sometimes needful.

    Last, at the end, some suggestions or words from the wise are not a bad idea, on the theory that some users will be new and this is a good place to pass on the 'common knowledge' of the competent folks. For example, "When turning off services, always keep 'Network' and 'Ssh' enabled, so that you avoid locking yourself out of your server."

    One more tip -- A human, for example, you, tends to be *brilliant* at organizing and making simple material when *explaining verbally* anything to another human. That same human will often flop around when attempting to do the same thing in writing. So if you want to get a clear organization of info, explain the thing verbally to somebody, while taping. You'll find lousy sentences, but brilliant clear organization. Then you write it out, cleaing up the lousy sentences. Try it; you'll see.

    Good luck with your project; I very much look forward to seeing your results.

    cPanel.net Support Ticket Number:
     
    #5 trakwebster, Jun 4, 2003
    Last edited: Jun 4, 2003
  6. Joshfrom

    Joshfrom Well-Known Member

    Joined:
    Jun 3, 2003
    Messages:
    157
    Likes Received:
    0
    Trophy Points:
    16
    Location:
    White Haven, PA, US
    I like your ideas... the one about branding seems like a definite possibility... My original idea was to have one official set of documentation just offered through cPanel, but offering a customizable set seems like a good idea as well.

    I myself am new to the cPanel and WHM products and am coming in with more or less a clean slate :) Anything I don't know, the end-user probably doesn't know as well. In my former position I wrote a lot of the documentation for our department and I tried to keep it as easy-to-understand as possible. In the end though it's you and your customers that have to use what I write, so I'll really be looking to you to see what you like and don't like.

    cPanel.net Support Ticket Number:
     
  7. xerophyte

    xerophyte Well-Known Member

    Joined:
    Mar 16, 2003
    Messages:
    216
    Likes Received:
    0
    Trophy Points:
    16
    Location:
    Canada
    My humble advice please make sure our time will be well spent. I read the current doc for the Cpanel and felt what a waste of time.

    cPanel.net Support Ticket Number:
     
    #7 xerophyte, Jun 4, 2003
    Last edited: Jun 4, 2003
  8. pirania1

    pirania1 Well-Known Member

    Joined:
    May 10, 2003
    Messages:
    126
    Likes Received:
    0
    Trophy Points:
    16
    Location:
    Miami, FL
    Also a comprehensive list of functions/applications will be a must.
    I have spent few days going thru cpanel files to figure out what applications it actually contains.
    List of addons etc..
    If the application is not developed by cpanel, include a link to the author.
    Each application should also have description:
    1. In short words what it does
    2. detailed "How to" use it.

    In general you have to follow "ways of use" path instead of listing functions (which is also good).
    When user is looking at manual (documentation) he has some task to perform (that's why he's checking it - he's looking for an answer), if the manual will be task-oriented it will be much user friendly.

    Also.. The main wish is to have it CONSTANTLY updated and included in disribution. Cpanel changes from release to release, and has TONS of undocumented functions. The only actual way to know about it, is to read changelog (if it's mentioned there ha ha) or to watch which binaries/files are modified by upcp (I use logwatch to track it).

    cPanel.net Support Ticket Number:
     
  9. ddent

    ddent Member

    Joined:
    Apr 8, 2003
    Messages:
    5
    Likes Received:
    0
    Trophy Points:
    1
    Example of woefully inadequate documentation: What on earth does the clustering function *actually* do, and how do I use it?

    cPanel.net Support Ticket Number:
     
  10. Website Rob

    Website Rob Well-Known Member

    Joined:
    Mar 23, 2002
    Messages:
    1,506
    Likes Received:
    0
    Trophy Points:
    36
    Location:
    Alberta, Canada
    cPanel Access Level:
    Root Administrator
    Nice to have you on board, Josh -- and here's hoping you can do what needs to be done in a way that will satsify the majority. :)

    Correct & Accurate information is all I ask for.

    "Cpanel can be used by the majority of people with an Internet connection."

    That maybe 'accurate' but is not correct.

    The coding for one, needs be cleaned up and brought uptodate with current HTML & CSS Standards. This is more of a problem with WHM/Cpanel themselves than for the documentation; IE for example, has more problems with some incorrect coding than say, Mozilla does. I mention it in the hopes that the 'trickle down' effect may kick in.

    Will having JavaScript turned on be a requirement? I would like to think so. A much better Navigation setup can be accomplished by using it. Although it's nice to have Web pages that work with any Browser, any connection speed, a certain level must be established and that information provided to people. They need to know what the basic requirements are, to properly read the Documentation.

    Top-down explainations and lots of pictures, will also go a long way in helping people. Examples would also be a nice touch and go hand-in-hand with explainations. More often than not, an example of what was just explained, goes a long way in helping to not only understand what was explained, but to also understand how & when to use.

    A top priority IMHO, is to state what is still in Beta or testing status. Too often new features are added and there are problems -- often when previous features have problems. Mentioning something is Beta or a 'heads-up, this may cause problems' type msg., would be a very nice feature. This will probably make a bit more work, as updating will be constant, but I presume, being hired to work specifically on the Documentation, that is the nature of the job and something you are ready for.

    cPanel.net Support Ticket Number:
     
  11. promak

    promak Well-Known Member

    Joined:
    Oct 6, 2001
    Messages:
    248
    Likes Received:
    0
    Trophy Points:
    16
  12. jsnape

    jsnape Well-Known Member

    Joined:
    Mar 11, 2002
    Messages:
    174
    Likes Received:
    0
    Trophy Points:
    16
    I'll second the motion to make it brandable.

    cPanel.net Support Ticket Number:
     
  13. Website Rob

    Website Rob Well-Known Member

    Joined:
    Mar 23, 2002
    Messages:
    1,506
    Likes Received:
    0
    Trophy Points:
    36
    Location:
    Alberta, Canada
    cPanel Access Level:
    Root Administrator
    Wanted to also mention, it would be nice to have all Categories and sub-listings alphabetized.

    Just a thought -- but a nice one. ;)

    cPanel.net Support Ticket Number:
     
  14. shaky

    shaky Well-Known Member

    Joined:
    May 31, 2003
    Messages:
    53
    Likes Received:
    0
    Trophy Points:
    6
    Keeping the information up to date, has to be vital. The current docs have lots of holes and I guess this is because of the nature of cpanel and WHM they are getting updates from time to time but the update info never makes it to the docs. Some of the features in WHM I have no idea what they do as there is no explanation that I can find, and I'm tired of playing trial by eror and crashing the server :)

    Absolutely!

    Good to see that someone has been allocated this responsibility so best 'o luck Josh.
     
  15. perlchild

    perlchild Well-Known Member

    Joined:
    Sep 1, 2002
    Messages:
    279
    Likes Received:
    0
    Trophy Points:
    16
    I second that... But cpanel implemented itself a solution to that...
    It's called the stable branch...
    It's not supposed to change much, so it's the perfect target for documentation...

    cPanel.net Support Ticket Number:
     
  16. trakwebster

    trakwebster Well-Known Member

    Joined:
    Jan 29, 2003
    Messages:
    145
    Likes Received:
    0
    Trophy Points:
    16
    Here's an idea that would be very useful for more advanced users, and that would be fairly simple to implement.

    In an appendix, list the scripts by name that are found in /scripts, and tell in one or two sentences what they do.

    For example, to do an update for cpanel, I can do a /scripts/upcp from the command line. This is easier than browsing and finding the equivalent. So a list of these 'command-line' scripts, which are a strength of your software, would give users more use of what you are already providing, and all it would require would be a list, and a couple of sentences for each item.

    Easy, useful, powerful.

    cPanel.net Support Ticket Number:
     
  17. rs-freddo

    rs-freddo Well-Known Member

    Joined:
    May 13, 2003
    Messages:
    832
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    Australia
    cPanel Access Level:
    Root Administrator
    There really needs to be some sort of "immediate" updates. Like if a new feature is added in an edge release - there needs to be documentation on what its supposed to do. I find that even by the time stuff hits "stable" there still isn't documenation on the feature/change.

    cPanel.net Support Ticket Number:
     
  18. perlchild

    perlchild Well-Known Member

    Joined:
    Sep 1, 2002
    Messages:
    279
    Likes Received:
    0
    Trophy Points:
    16
    Interesting idea... I hold an opposing view, it shouldn't hit stable if it hasn't been documented, period. Security updates are one thing, security "features" have a one in two chance of causing more trouble than they heal...
    Let's at least take the time to understand them(and let administrators of "stable" boxes the time to understand them)

    cPanel.net Support Ticket Number:
     
  19. jamesbond

    jamesbond Well-Known Member

    Joined:
    Oct 9, 2002
    Messages:
    738
    Likes Received:
    1
    Trophy Points:
    18
    For the documentation, I would suggest using good software like http://www.ehelp.com/products/robohelp/ instead of putting together some html pages.

    Modernbill uses this software, and their documentation is excellent (especially when you compare it to CPanel's)

    cPanel.net Support Ticket Number:
     
  20. jayray

    jayray Registered

    Joined:
    Jun 25, 2003
    Messages:
    1
    Likes Received:
    0
    Trophy Points:
    1
    I would like to see popups with basic explanations and links to howto examples and why or why not to use a certain feature.

    For most of us newbies many features are just words with no meaning

    thanks.

    cPanel.net Support Ticket Number:
     
Loading...

Share This Page