ubuntu-manual team mailing list archive

[Jonathan Aquilina <eagles051387@xxxxxxxxx>]

I think the comments would actually work hand in hand with ask.

The problem with the community docs if they are not moderated, we could run
into the issue of anyone updating a page with total and utter crap. How do
the community docs are ensured that the material even small corrections are
accurate?


On Wed, Oct 9, 2013 at 11:32 AM, Tom Davies <tomdavies04@xxxxxxxxxxx> wrote:

> Hi :)
> I think the crucial difference is that the Community Documentation is
> fairly easy for anyone and their granny to update.  This tends to make it
> friendlier and in many cases more up-to-date and usable than the official
> documentation.
>
> As someone works through a page if they spot an easier way of phrasing
> things or a more logical or easier to understand route then they can edit
> even as they try to follow instructions.  People who are shy can add
> comments and questions to the bottom of pages so that others can
> incorporate their ideas later.
>
>
> It is being suggested that allowing official docs to have comments at the
> bottom might be good but then who would be willing to be "moderator" and
> how many people would be available to answer the questions there?  Would we
> encourage people to leave Ask Ubuntu, Launchpad Answers and Ubuntu Forums
> in order to use a tool that is not really designed to be much good for
> dealing with questions?  As it is people do write questions at the bottom
> of some of the Community Documentation pages and those questions generally
> don't get answered.
>
> So by attempting to combine resources we end up with other, more clumsy,
> splits in other teams.  I think 2 teams working together through liaison
> people (such as Kevin) is probably more efficient.
> Regards from
> Tom :)
>
>
>
>
>   On Wednesday, 9 October 2013, 5:51, Kevin Godby <godbyk@xxxxxxxxx>
> wrote:
>  On Tue, Oct 8, 2013 at 6:16 PM, Phill Whiteside <PhillW@xxxxxxxxxx>
> wrote:
> > at present we have separate teams all trying to achieve the same thing.
> None
> > of the teams have enough people... Is it really too scary for us to all
> pool
> > what meagre resources we have in what is called 'man hours' to instead
> run a
> > manual system for 14.04 which is split between "desktop" and "server" ?
> Each
> > can provide links to the other... To me, it just makes sense.
>
> I will briefly examine three forms of documentation for the Ubuntu
> desktop:  (1) the system documentation, (2) the wiki documentation,
> and (3) the Ubuntu manual.
>
> (1) The system documentation is maintained by the ubuntu-docs team
> (primarily the ubuntu-docs-committers team) and is available in two
> formats: online at
> <https://help.ubuntu.com/13.10/ubuntu-help/index.html> and through a
> desktop application (available by searching for 'help' in the Dash).
>
> The system documentation consists primarily of procedures for
> performing specific tasks. It doesn't provide much background
> information or ancillary information. It assumes the reader knows
> precisely what she wants to do and walks her through the steps to
> achieve that goal.
>
> The reader must either have access to the Internet or be able to boot
> to Ubuntu to read the system documentation.
>
> The system documentation is packaged and translated each cycle.
>
> (2) The wiki documentation is maintained by the entire Ubuntu
> community and is available online at
> <https://help.ubuntu.com/community>. Anyone can modify or create wiki
> pages.
>
> The style of the wiki pages varies wildly. Some wiki pages provide
> background information or discussion of a topic while others provide
> task-driven, step-by-step procedures for accomplishing specific tasks
> or troubleshooting a problem.
>
> The reader must have access to the Internet to read the wiki documentation.
>
> The wiki pages may be updated at any time throughout a cycle and don't
> adhere to any particular deadlines.
>
> (3) The Ubuntu manual project is maintained by the ubuntu-manual team.
> The manuals are available as printed-and-bout books via
> CreateSpace.com and Amazon.com sites for the cost of printing.  A PDF
> version of the manual is available for free download at
> <http://ubuntu-manual.org/>.
>
> The manual provides step-by-step instructions for various procedures
> (including installing Ubuntu) and also provides a bit more background
> discussion of some of the underlying concepts.
>
> The reader must either have access to the Internet to download the PDF
> or have purchased a printed copy of the manual.
>
> The manual is updated once per cycle and is translated into a handful
> of languages.
>
>
> Before we assume that all of these documentation projects cover the
> same ground, I think we should take the time to define their audiences
> and goals.  Each of the projects has its pros and cons.
>
> For example, while the system documentation and the manual cover a lot
> of the same material, the manual provides more background information
> and screenshots than the system documentation (which is helpful for
> beginners). The manual is available in print form for offline reading,
> but the system documentation is translated into more languages.
>
> The wiki covers a wider variety of topics, but often contains a lot of
> outdated and incorrect information. Not as much of the wiki is
> translated to other languages. But the wiki can be updated more
> frequently than the system docs or the manual.
>
> One might be naively tempted to simply print out the system
> documentation and call it a manual, but it wouldn't be a very good
> manual. It's be a collection of procedures with no transitions and
> little underlying structure. A reader would find it difficult to read
> the system documentation without having a particular question or task
> in mind; the manual is much more conducive to arm-chair reading.
>
>
> Having said all that, these documentation projects do have quite a bit
> in common, however. Each of the projects needs to work hard to stay up
> to date with the latest Ubuntu developments. Collecting information on
> how new versions of software applications and desktop environments
> have changed is a very time-consuming and often incomplete task.
> Pooling our resources on this front, for example, would be a boon for
> all the projects.
>
> —Kevin
>
>
> --
> ubuntu-doc mailing list
> ubuntu-doc@xxxxxxxxxxxxxxxx
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>
>
>
> --
> ubuntu-doc mailing list
> ubuntu-doc@xxxxxxxxxxxxxxxx
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>
>


-- 
Jonathan Aquilina