Ubuntu Community Documentation: CHANGELOG #1

Sat Jun 11 05:14:41 UTC 2011

Here is a fairly comprehensive list of changes I have made to the main page
and saved in the Draft.

Howzzat?

1) Removed "See Also" from top and moved them to the bottom, where there is
a similar section (more appropriate).

2) Moved "Finding your way" signpost from top to bottom, as well as the
browsing by category section, since it better serves its purpose akin to the
index pages of a book.

The reason I did the above two is because I feel that when a newbie goes to
the Wiki, he should be greeted first by the "Getting Started" section.
Asking the user to diverge to different pages straightaway does not seem
very appealing to me.

3) Added the new Ubuntu logo - mostly for 'catchiness' value. I would like
this logo to be centered, but the ";position=middle" command with the
attachment does not help. Maybe I have to put it in a table environment as
in LaTeX?

4) Getting Started with Ubuntu (changed to "Getting Started!"):

5) Added the words "as you go along" to the referring line to the Glossary,
to not give the impression that the newbie should master the glossary before
proceeding any further. A few more changes to that sentence (again, this and
all the changes I shall make shall be from thinking from the perspective of
what the newbie would like to hear. I think that is a difficult art to
master and I am still learning that from my experiences with students in the
classroom).

6) I think the first section somebody should see is "Installation Guide",
because that is where they shall be starting from. I merged the "Switching
form another OS" section with this section, since it is redundant having two
of those.

7) The Terminal... Added some lines explaining this might be a new idea
especially of switching from another distro. Rewrote the sentence that
follows.

8) Getting to Know... Minor changes

9) Software: Removed the line about "the hardware side of networking" - this
section is immediately above and is therefore redundant, since the reader
has to have seen it before coming here.

I think the tone of the documentation now seems a bit warmer than before.
Pray give me feedback/suggestions? I will try to incorporate further changes
as and when they pop up again (I must run now to attend to "life"). I wish
to actively contribute to making the documentation of the Perfect Operating
System perfect!

I would like to add this: yes, we are geeks, ipso facto that we use
GNU/Linux. However, the one philosophy that Ubuntu has tapped upon, which
sets it apart from every other distribution out there and makes it
accessible to the masses, is the age-old idea of encapsulation - hiding the
internals from the end user (indeed an idea also employed by Apple), an idea
which allows one to pick and choose their battles; from being the geekiest
of geeks to the "I-just-want-my-machine-to-work" philosophy. It would be
phenomenal if the entire documentation can mirror that same philosophy!

Manjul

On Fri, Jun 10, 2011 at 11:29 PM, Manjul Apratim
<manjul.apratim at gmail.com>wrote:

> Okay... as asked on the editing options for the homepage to the Community
> Documentation, I shall first be making changes to the Draft. Then I will
> show up and ask again for opinions regarding the changes I made.
>
>
> On Fri, Jun 10, 2011 at 10:57 PM, Manjul Apratim <manjul.apratim at gmail.com
> > wrote:
>
>> I agree with most arguments presented here, and I would not wish to have
>> any of the relevant forum sections removed or have the documentation be
>> created from scratch.
>>
>> I would like to, however, chart out a concrete plan of attack to make the
>> Ubuntu knowledge base immaculate, at least as much as Arch's.
>>
>> My proposals:
>>
>> 1) I would like to see the frontpage "help.ubuntu.com" merged with the
>> frontpage "https://help.ubuntu.com/community". Before I receive raised
>> eyebrows for this, pray let me elucidate: The "help.ubuntu.com" part is a
>> tiny page anyway, and it could be made an opening section of the resulting
>> page, with the title "Official Installation Guide". The pages linking from
>> it for each release starting from Dapper could still be left immutable.
>>
>> 2) I will start from "ground up" - basically, over the next couple of
>> weeks or so (I would like to start right NOW but I am extremely busy; I
>> shall have to do this when I am taking a break or so), I shall try to make
>> extensive changes to the opening page of the community documentation. This
>> is because putting myself in the shoes of a newbie, I do not really like how
>> the page is organized nor much of what is on the page (compare this with how
>> the new Ubuntu installer greets you). I will make the changes as I feel are
>> appropriate, and then paste an appropriate "changelog" here, asking people
>> for feedback. The best thing about this is that since this is the best form
>> of "peer-review", it can only get better. I will proceed to the linking
>> pages in due course.
>>
>> 3) Some of the pages that link from the first page, for instance:
>>
>> https://help.ubuntu.com/community/CategoryCategory
>>
>> look like simply, for the lack of a better word, YUCK! Even if the pages
>> linking from that page are to remain named "CategoryXXX", there is no reason
>> the word category should appear in the text corresponding to each link,
>> making it appear a million times on that page. I would like to remove the
>> word "Category" from all those links.
>>
>> I will post later as I think of more ideas.
>>
>> Manjul
>>
>>
>>
>> On Mon, Jun 6, 2011 at 7:48 PM, Connor Imes <rocket2dmn at ubuntu.com>wrote:
>>
>>> Hi all,
>>>
>>> On 06/05/2011 08:50 PM, Jorge O. Castro wrote:
>>> > On Sun, Jun 5, 2011 at 6:44 PM, Manjul Apratim <
>>> manjul.apratim at gmail.com> wrote:
>>> >> I realize that by spurring this discussion I am opening a can of worms
>>> that
>>> >> has long existed and been reiterated upon continuously
>>> > Thanks for bringing this up. I have a talk at UDS about how horribly
>>> > out of date our documentation is, and have been asking people to go
>>> > back and clean up after themselves.
>>> >
>>> > http://castrojo.tumblr.com/post/5651069099/cleaning-up-after-ourselves
>>> >
>>> > I have some comments about your ideas:
>>> Nice screenshot of RecentChanges :)
>>> >> problem that there is a wealth of information in the forum archives
>>> that is
>>> >> just sitting there inaccessible to most new users without extensive
>>> >> searching, and which urgently needs to become part of the wiki. The
>>> very
>>> >> fact that the documentation is not centralized nor easily accessible
>>> makes
>>> >> potential contributors refrain from contributing to it.
>>> > The wiki has lasted as long as the forums have existed and there have
>>> > been multiple attempts to get information out of the forums and into
>>> > the wiki. Ideally the "Tutorials and Tips" section shouldn't even
>>> > exist, as it encourages people to duplicate information, and since
>>> > it's a forum, no one except the original poster can fix it, which
>>> > means if someone is wrong someone else can't fix it.
>>> I've been working as staff on the forums and as a wiki editor/admin for
>>> a number of years now, and I find myself disagreeing with this point.
>>> While there are some guides on the forums that may be useful, at least
>>> partially, on wiki pages, most forums guides end up being very specific
>>> in their intent.  Many are targeted at a particular set of hardware or a
>>> more complex task than simply getting something working.  These types of
>>> guides are also more difficult to maintain across multiple releases and
>>> in the cases that they have been moved to the wiki, they usually go
>>> unmaintained and quickly become deprecated.  I expect this is because of
>>> their complexity or are just too specific for many people to care about
>>> or even have the knowledge to accurately maintain.
>>>
>>> I have found that the best-maintained wiki pages cover a broad topic or
>>> set of hardware such that the material is applicable to many users, esp.
>>> to beginners.
>>> >> Instead, the path that leads to the actual
>>> >> "wiki" - the community edited documentation, is obscure and of course,
>>> a
>>> >> simple Google search for "Ubuntu wiki" on the web leads to no useful
>>> >> technical documentation directly. In fact, a user may be thrown off by
>>> the
>>> >> fact that the pages ask him to refer to the "official documentation"
>>> as well
>>> >> as the "community contributed documentation".
>>> > I'm not convinced this is a problem. Most people will just search for
>>> > the problem in Google and go where they end up. Unfortunately for us
>>> > Google penalizes slow web sites, which means that many times the
>>> > results from the official wiki won't be on the front page of a search.
>>> > Fortunately the IS team has been working on this problem and we should
>>> > see performance improvements in the following weeks.
>>> >
>>> >
>>> >> Take the example of Arch Linux. It has probably the most excellent
>>> Wiki one
>>> >> could ask for; there's Arch, and there's the ArchWiki. New users
>>> installing
>>> >> Arch are referred to the Wiki - and most of the qualms a new user may
>>> have
>>> >> may be solved directly by reading the wiki - there's no five different
>>> >> places a user has to refer to to find what information is relevant and
>>> what
>>> >> is out of date.
>>> > Our wiki is 7 years old and has 7 years of information to clean up, of
>>> > course a newer wiki will be cleaner. I don't understand how we can fix
>>> > the "send people to the wiki" problem other than fixing the wiki and
>>> > telling people to go to it.
>>> >
>>> >> In contrast, there are some veterans on the Ubuntu forums
>>> >> which have posted several great HOWTO's there, but these really belong
>>> in a
>>> >> central place on the Wiki, along with other good documentation that
>>> pops up
>>> >> from time to time.
>>> > Really someone should propose to move all the HOWTOs to the wiki and
>>> > shut down the section in the forums.
>>> Again a -1 from me.  Just have a look at some of the topics for guides
>>> [1].  As I said above, many are quite specific and can be rather
>>> complex.  A good chunk of these require more than a beginners knowledge
>>> base to use effectively (or safely for that matter).
>>>
>>> [1] http://ubuntuforums.org/forumdisplay.php?f=100
>>> >> 2> The "Community Contributed Documentation" may be renamed as the
>>> "Ubuntu
>>> >> Wiki", and linked to directly from the homepage - preferably somewhere
>>> near
>>> >> the top right corner.
>>> > I don't think end users will care about the word "wiki". Making the
>>> > information more relevant so the site performs better and shows up
>>> > better on search engines seems like the way to fix this for real.
>>> >
>>> It might help to integrate the wiki(s), system documentation, and
>>> ubuntu.com better.  There are some links on the Support page [2], but
>>> after that the user is on their own to navigate.  A common header
>>> section might be beneficial.
>>>
>>> [2] http://www.ubuntu.com/support
>>>
>>> Cheers,
>>> -Connor
>>>
>>
>>
>>
>> --
>> Manjul Apratim
>>
>
>
>
> --
> Manjul Apratim
>

-- 
Manjul Apratim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20110611/feb5cf9f/attachment.html>