Mactel Documentation Planning

[cyberdork33]

I installed ubuntu on the mac two weeks ago for the first time.
And I can just say, that the pages are a bit confusing.

I agree

You have noticed, that I looked in the wrong wiki.
I did know about the Santa Rosa pages, I found them in the
literature list of an article about installing ubuntu on a mac
book in the german magazine "CT". But I didn't care about it, because
1) its written for gutsy 2) I don't know what Santa Rosa is.
The "Mac geek" in my department didn't knew about it today either.

Well the base MacBook page has a note at the top... "If you own a MacBook of the Santa Rosa generation (v3.1 and v4.1) see this guide..."

The MacBook has this really really great feature to give an unique
hardware identification. So, if anybody refers to a MacBook in a wiki
it should always be "MacBook, + identification string".

Yes, in fact, all Macs have this ability, bit nobody uses it. You can see that I have a link in my signature about properly identifying your Mac and linking to the correct wiki pages. (The "before you post" link).

A newbee like me should be able to find the right wiki in just a matter
of seconds. This also means, that the actual page "MacBook ubuntu user documentation" must be renamed.

go for it. Since it is a wiki, you can edit it as well.

I also think, sombody how likes to install ubuntu will/should always
use the latest version. So all wikis should be up-to-date
with the RC comming out.

While that is true, keeping older documentation around can be helpful too, though I think the "main page" needs to be completely up to date.. Kosumi has suggesting creating a new page for each Ubuntu release. You can see this with some of his MacBookAir pages.

Please give me some time. I really like to see what you already did
and use it. I also like to discuss everything here. Nobody can do
this alone, because it needs a lot of MacBook owners to report
their experiences.

yes, the more help the better.

[cyberdork33]

Ok, first for anyone that is planning to create / edit / update wiki pages,

The pages under "wiki.ubuntu.com" are not for support documentation. That wiki is for Teams and organization. This is where I have placed a bit of "mactel-support" team info.

https://wiki.ubuntu.com/MactelSupportTeam
https://wiki.ubuntu.com/MactelSuppor...unityHelpPages
https://wiki.ubuntu.com/MactelSupportTeam/PPA

The How-Tos and hardware docs should go in the community help wiki under the URL "help.ubuntu.com/community". This includes the installation guides and such that most users use to install Ubunt on their Mac. Examples:
https://help.ubuntu.com/community/MacBook
https://help.ubuntu.com/community/MacBookPro

Please be sure to place infomation is the correct location so that others can find it easily. Also, if there are any pages in the wrong location, they should be moved and a link placed in the old page.

[kosumi68]

Inside the community wiki, one can redirect to new pages by keeping a single line in theo old page:

#redirect newpagename

However, I don't know if this works between wikis.

[kosumi68]

Cyberdork, it's great that you copied that PPA page over, but many of the links broke and needs fixing... there is a nice feature called 'which pages link to here' to repair such things.

[beauman]

Hi!

What we need, is a meta structure for wikis about ubuntu on intel macs.

It's supposed to lead an owner of such a hardware to the right
wiki page.

You can find out, what your Macintosh hardware is, by typing
the following command in a terminal:

sudo dmidecode| grep Product

or

you can look it up under OS X (Apple-> About this Mac -> Details)
[What is the original text in english?]



Ubuntu supports:

MacBook
MacBook Pro
MacBook Air
iMac (Intel based)
Mac mini
Mac Pro (Intel based)

The following hardware versions of these Macintosh products are supported:

MacBook:
- 1,1
- 2,1
- 3,1
- 4,1
- 5,1
MacBook Pro:
- 1,1
- 2,1
- 3,1
- 4,1
- 5,1
MacBook Air:
- 1,1
- 2,1
iMac:
- 4,1
- 5,1
Mac mini:
- 1,1
- 2,1
Mac Pro:
- 1,1
- 2,1
- 3,1

(Correct me, if something is missing or wrong)

I count 19 different hw platforms.

Our wiki should link a user to a wiki of his hardware and the actual
ubuntu version, which is 8.10 "Intrepid Ibex" at the moment. Also,
we should link to other versions of ubuntu like the LTS version,
which is 8.04.1 "Hardy Heron".

We should not bother the user with versions of ubuntu, that are not
mentained anymore, like Gutsy and older.

The question is now, if each combination should have it's own wiki named

Mac Product Name --- Mac Model-Identification --- Ubuntu Version

(short Product/ID/Ubuntu)

or if we should try to merge several version/Model ID's into one wiki.

I would prefere Product/ID/Ubuntu.

We also need mentainers for the 19 hw platforms. These mentainers
should also start beta testing a new ubuntu version and
prepare the page for the upcoming release. If they encounter
any bugs, they should link them (or even post them) to
launchpad bug-reports, so users can see what the actual status of the
bug is.

If a certain ubuntu version does not support a hardware in a
satisfying way, we should not recommend this version. Hardy Heron for
example does not support LAN, wireless and sound on the
MacBook 4,1.

A wiki for a spezific hardware could contain a table of build-in
hardware and hardware functions which:
- run out-of-the-box
- need manual installation
- will not work at the moment

We should try to think a little bit Mac and not Linux, so
we should not mention the processor name or certain chipsets
in the wiki headline (like penryn and sankta rosa; I searched
for it on the apple site with no relevant results; also the
Hardware overview of OS X does not mention it either)
Also, your name creation "Mactel" must be explained, before you
use it in a wiki.

We should use all existing wikis that fit into our hardware/ubuntu
matrix, if it's ok for everbody, that we maybe alter the headline
to our naming style or change something else.

The wikis should just serve as the purpose to help a user
improve their installation. "Internal" remarks should be
placed at the end of the wiki or in a mactel support wiki.

All common questions for the Mac side like rEFIt, diskutil or mountig ext3
should be placed in a central wiki. Only if a hardware needs specific
instructions for OS X we put it on the spezific hardware wiki.

We should try to be exact with names and spelling.
It's "MacBook Pro" but "Mac mini". My native language
is german, so correct me whereever you can.

Also, we should think about translating the wikis to other
languages than english.

I like the pictures in the MacBookPro wiki.

Regards,
beauman

[kosumi68]

beauman, nice post!

Small thing: I have seen examples of iMac8,1.

Big thing: Structure can only be suggested, not enforced. I like your structure idea a lot, and starting work in that direction, talking to the people who maintain the pages, is possible. However, copying all pages somewhere and expecting people to follow is not realistic. It will have to be an organic growth, led by good examples.

That said, I believe there is an opportunity right now, since we currently lack quite a few pages about Intrepid. The new pages can be placed into the structure you propose. The old ones should simply be left alone. It only takes about a week for a new page to become established as the top google page, so linking to the new pages is not really an issue.

[freakalad]

For my MBP SR 3.1 single-boot:

Found Intrepid has some pretty good support for hardware.

There are issues with pommed, but this is probably mostly due to the fact that the original developer has since moved on to bigger & better things.

Found Envy to be the simplest way of dealing with video issues

[cyberdork33]

Inside the community wiki, one can redirect to new pages by keeping a single line in theo old page:

#redirect newpagename

However, I don't know if this works between wikis.

Good to know. I was wondering about that. Maybe if you use the entire URL?

Cyberdork, it's great that you copied that PPA page over, but many of the links broke and needs fixing... there is a nice feature called 'which pages link to here' to repair such things.

ah crap. I did it in a bit of haste today. I usually just put the whole page URL as a link myself so I don't think about it otherwise.
I also made a common page for the iSight.

iMac:
- 4,1
- 5,1
Mac mini:
- 1,1
- 2,1
Mac Pro:
- 1,1
- 2,1
- 3,1

I think that the Intel iMacs are versions 4,1 - 8,1 right now

There was at least one PPC Mac Mini, so probably 2,1 and 3,1

Mac Pros have been around forever, so I have no idea what version they are on...

There are also Xserves (RackMac). I have no idea on the version numbers for it. We have had a few posts on Xserves in the past.

Our wiki should link a user to a wiki of his hardware and the actual
ubuntu version, which is 8.10 "Intrepid Ibex" at the moment. Also,
we should link to other versions of ubuntu like the LTS version,
which is 8.04.1 "Hardy Heron".

We should not bother the user with versions of ubuntu, that are not
mentained anymore, like Gutsy and older.

agreed

The question is now, if each combination should have it's own wiki named

Mac Product Name --- Mac Model-Identification --- Ubuntu Version

(short Product/ID/Ubuntu)

or if we should try to merge several version/Model ID's into one wiki.

I would prefere Product/ID/Ubuntu.

I think that each platform and version should have a page definitely, plus maybe an extra for the last LTS release. A lot of hardware is the same for different Macs (the Broadcom WiFi cards are command across many Macs for instance.) These can be put on subpages that can be linked in each of the platform pages. Example:
https://help.ubuntu.com/community/AppleiSight

We also need mentainers for the 19 hw platforms. These mentainers
should also start beta testing a new ubuntu version and
prepare the page for the upcoming release. If they encounter
any bugs, they should link them (or even post them) to
launchpad bug-reports, so users can see what the actual status of the
bug is.

The hard part here will be finding the people to dedicate to making these changes all the time. Linking all bug reports might be a little extreme... maybe there could be a single page under the mactel-support team pages for the bugs. (You can actually reach most of these through the mactel-support pages on launchpad.)

If a certain ubuntu version does not support a hardware in a
satisfying way, we should not recommend this version. Hardy Heron for
example does not support LAN, wireless and sound on the
MacBook 4,1.

IDK. Everyone is going to want to run the latest on the latest. People ran Hardy on MacBookPro4,1. I probably would have too if I had one to run it on. Maybe a warning, but still have the information to do it.

A wiki for a spezific hardware could contain a table of build-in
hardware and hardware functions which:
- run out-of-the-box
- need manual installation
- will not work at the moment

good organization. I like this approach.

We should try to think a little bit Mac and not Linux, so
we should not mention the processor name or certain chipsets
in the wiki headline (like penryn and sankta rosa; I searched
for it on the apple site with no relevant results; also the
Hardware overview of OS X does not mention it either)
Also, your name creation "Mactel" must be explained, before you
use it in a wiki.

I agree with that, unfortunately, that is just how people come to recognize things here, and hardly anyone pays attention to the real version number of the machines. The other common method to to identify by release date... i.e. MacBook (Late Oct 2008 )

Mactel is a pretty common term for Intel Macs in general. It was not made up here, but brought here from the Apple Users.

We should use all existing wikis that fit into our hardware/ubuntu
matrix, if it's ok for everbody, that we maybe alter the headline
to our naming style or change something else.

The wikis should just serve as the purpose to help a user
improve their installation. "Internal" remarks should be
placed at the end of the wiki or in a mactel support wiki.

agree. The existing pages need a bit of cleanup. Also, it is difficult to enforce this on pages that are not "ours". People often get quite offended if you delete things they added to the wiki and really they have every right to put it there just like we do.

All common questions for the Mac side like rEFIt, diskutil or mountig ext3
should be placed in a central wiki. Only if a hardware needs specific
instructions for OS X we put it on the spezific hardware wiki.

Yes. Basically the base install is the same for every mac. this could be put on a single page and linked at the beginning of each platform page.

I like the pictures in the MacBookPro wiki.

me too. We have an official "Ubuntu mactel-support" logo too. (It is on the launchpad page).
https://launchpadlibrarian.net/12033...ubuntu_192.png

Big thing: Structure can only be suggested, not enforced. I like your structure idea a lot, and starting work in that direction, talking to the people who maintain the pages, is possible. However, copying all pages somewhere and expecting people to follow is not realistic. It will have to be an organic growth, led by good examples.

That said, I believe there is an opportunity right now, since we currently lack quite a few pages about Intrepid. The new pages can be placed into the structure you propose. The old ones should simply be left alone. It only takes about a week for a new page to become established as the top google page, so linking to the new pages is not really an issue.

Agree. I think that trying to reorganize the existing information is a good way to do that. Also, we should publish these guidelines on the wiki page as well to show that there is agreement on this, and users are general expected to follow the guidelines.

Leaving the old pages can be confusing though. When you have a page that seems to cover all MacBooks, but then they should really be reading the MacBook4,1 Intrepid page...

I think I am going to request a social group be created too. That will allow there to be "mactel-support members" to exist in the forums.

[cyberdork33]

Join the mactel-support social group!

We can share pictures and have conversations there.

http://ubuntuforums.org/group.php?groupid=352

[beauman]

Hi! You people are really open to new ideas, that is great!

I agree to everything you said.

Especially on identifying a Mac. I spoke to two
Mac fans today. Both knew the realse date of
their hardware, none of them knew the Model-ID.
The release date seems to be more important.

The head line of a wiki could be:

Mac Product Name - (Release Date) -Mac Model-Identification -Ubuntu Version

I think that the Intel iMacs are versions 4,1 - 8,1 right now

There was at least one PPC Mac Mini, so probably 2,1 and 3,1

I triggered one of the guys to check out the Modell-ID of his Mac mini.
He knew that it's second generation intel. The list of models can we
discuss, when we have created a page.

I think that each platform and version should have a page definitely, plus maybe an extra for the last LTS release. A lot of hardware is the same for different Macs (the Broadcom WiFi cards are command across many Macs for instance.) These can be put on subpages that can be linked in each of the platform pages.

Yes, subpages are good, especially it's less work when
things change. The allover hierarchy should not be to deep.
People should not be bothered to much with different hardware
than they have. The wiki of their hardware should be easy and clearly arranged.
We can put several wikis together, if it's the same release date
and Model-ID. Example:

MacBook and MacBook Pro (Release Feb. 2008 ) - 4,1 - Ubuntu 8.10 "Intrepid Ibex"

The hardware should be very close and not differ in more than a couple
points.

The hard part here will be finding the people to dedicate to making these changes all the time.

Let's just try it

Linking all bug reports might be a little extreme... maybe there could be a single page under the mactel-support team pages for the bugs. (You can actually reach most of these through the mactel-support pages on launchpad.)

Okey dokey

... Everyone is going to want to run the latest on the latest. People ran Hardy on MacBookPro4,1. I probably would have too if I had one to run it on. Maybe a warning, but still have the information to do it.

Yes, ok. We link to the actual and to the LTS release. Since the LTS is for
half a year the actual version, there will always be a wiki anyway.
And if we integrated a table of features that "work out-of-the-box/have to
be installed by hand/ won't work", pleople can decide if the prefere
long term support over supported features.

Mactel is a pretty common term for Intel Macs in general. It was not made up here, but brought here from the Apple Users.

If we use the word, we should just introduce it. So that people
don't think it's a special hardware they don't have.

The existing pages need a bit of cleanup.

We should talk with the people how wrote the pages. Maybe they
like our idea to find a better structure of the Mac wikis.
Or maybe they permit us to change it a bit.

Leaving the old pages can be confusing though. When you have a page that seems to cover all MacBooks, but then they should really be reading the MacBook4,1 Intrepid page...

Yes. Let's just see. If the structure becomes accepted and people
realize, that we a have clear and concise way of helping users,
they might use it and link it. Maybe a search will show us first then.
Or if the they have found both pages, they might prefere ours, because
it looks more accurate and comprehensive.


Ok. So far, so good.

Let's go for the first step:

What pages do we need?

I would say:

- the meta wiki that helps/introduces the user to ubuntu on mac
and helps him find the exact wiki he needs.
- a page for wiki guide lines and for wiki developers
- a discussion thread

First we should think a about a name for the meta page.
A question is, if we should mention, that it's just
for Intel. I would not restrict it to Intel,
to have it more common. You never know what's
happening in the future. And maybe someday people like
to add a wiki for ubuntu on PPC.

I would suggest:
"Ubuntu on Mac" (short is good)
or "Installing And Maintaining Ubuntu On Mac Hardware"
Some other ideas?


To the wiki about our documentation ideas:
We can call it "Ubuntu Mac Documentation" or whatever,
it's just internal anyway.

And we can continue this thread for a long time.

If we have agreed on a title for the meta wiki, we
can create it. I then like to write the table of
the different supported hardware platforms (So I get familiar with the
markup language )

We can then discuss in detail, what hardware platforms
are supported and when they were released by Apple.

If we have a common sense for our goals, naming conventions
and so on, we can create the development wiki.

With these three sites, which sketch our idea,
we can then try to reach other wiki writes
and invite them to join via private messages
our in forums.

So long,
beauman