Results 1 to 8 of 8

Thread: Ubuntu documentation

  1. #1
    Join Date
    Dec 2007
    Beans
    12,521

    Ubuntu documentation

    Just in case people are interested, there's a discussion that seems to have started here: One set of documentation needs to go and I found that link in an Ask Ubuntu chat transcript that started with here.

  2. #2
    Join Date
    Jul 2008
    Beans
    2,732

    Re: Ubuntu documentation

    @vasa1, Thanks for bring this forward. No reason why they shouldn't be the same. It would defiantly be a big job off the start but likely easy to maintain after it was done.

  3. #3
    Join Date
    Dec 2007
    Beans
    12,521

    Re: Ubuntu documentation

    I think there needs to be a very clear public statement from the very top about what exactly should be what. People may feel this is anti-community or that there should be several alternatives for those seeking help. Unfortunately, quality, in terms of keeping content updated, is suffering. Ubuntu doesn't really have that many volunteers to ensure quality in each of the existing help options.

  4. #4
    Join Date
    Jul 2013
    Location
    Wisconsin
    Beans
    4,950

    Re: Ubuntu documentation

    This was discussed at the online Ubuntu Developer Summit in early November 2013.
    The Ubuntu Documentation Team is working the issue (among many others), and welcomed input in the cited email thread...before it diverged. I never did see any specific cases mentioned (perhaps I missed it).

    If you want some kind of statement "from the top," here it what I suspect it would be:
    When you find community documentation that conflicts with official documentation, report it.
    Send an email explaining the issue to the doc team at ubuntu-doc@lists.ubuntu.com. They will deconflict it.
    Last edited by ian-weisser; December 10th, 2013 at 01:38 PM.

  5. #5
    Join Date
    Aug 2005
    Beans
    6,024

    Re: Ubuntu documentation

    Ubuntu should look at the documentation from the likes of Debian, FreeBSD, Arch Wiki, Gentoo Wiki (well that recently suffered a horrible fate) as I think a lot could be learned from those projects and how they handle documentation.

  6. #6
    Join Date
    Nov 2011
    Beans
    2,336
    Distro
    Ubuntu

    Re: Ubuntu documentation

    Fedora's documentation is also very good.

    Documentation for Linux faces a number of challenges, I think. First, has anyone ever postponed the release of a distribution to allow time for the docs to catch up? Change comes fast and furious. Every patch and every bug fix creates a parallel need to be documented. These things often are quickly noted in mailing lists, bugzillas, on Launchpad, and other places, but the need is there for them to be recrafted in user-speak and made accessible at a single location rather than scattered about in sites that are not user-friendly.

    Existing documentation needs to be edited to reflect changes. Conflicting or confusing documentation needs to be fixed or eliminated. Documentation known to be incorrect should be edited or deleted.

    Ideally, distributions need to have *one* recognized location where users know they can find effective and trustworthy docs. Wouldn't it be nice to be able to turn to a single authoritative source rather than sift through hundreds of dubious hits returned by Google?

  7. #7
    Join Date
    Dec 2007
    Beans
    12,521

    Re: Ubuntu documentation

    Quote Originally Posted by buzzingrobot View Post
    ... the need is there for them to be recrafted in user-speak and made accessible at a single location rather than scattered about in sites that are not user-friendly.

    ...

    Ideally, distributions need to have *one* recognized location where users know they can find effective and trustworthy docs. ...
    +1.

    Re. sites that are not user-friendly, even if they are user-friendly, someone needs to watch over them. That's not happening, and given the reality, it's close to impossible.

  8. #8
    Join Date
    Nov 2011
    Beans
    2,336
    Distro
    Ubuntu

    Re: Ubuntu documentation

    Quote Originally Posted by vasa1 View Post
    +1.

    Re. sites that are not user-friendly, even if they are user-friendly, someone needs to watch over them. That's not happening, and given the reality, it's close to impossible.
    it's not so much a matter of "user-friendly" design as it is that sites like LaunchPad, the bugzillas, etc., are built for developers trying to deal with bugs, not users looking for guidance on how to use software.

    Independent sites can't be controlled, as you say. The net is littered with bad advice, and much of it is recycled and republished endlessly. All we can hope is that an officially sponsored documentation site gains a reputation for quality and thoroughness so people look there first.

    Documentation in the commercial arena, where professional writers are paid to create it, is often dicey. So, it's no wonder that in Linux it's problematic.

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •