DocTeam write-up

[sparkes]

Alexander Poslavsky wrote:
> Hi guys(mv)!

hey, dude,

It's a long reply so hang on.
> 
> After our discussion on irc about not discussing on irc i decided to
> do a write-up on my thoughts on how things are going on the
> ubuntuwiki. The first thing to say is that it is going really well. We
> have lots of really nice pages and quite a number of different
> contributors. In short, for such a new distro, not bad at all.
> What is not so good? I wrote some thoughts. What do you guys think?

it's true that we need to keep as much discussion on the list for a 
couple of reasons.  The first is inclusivity (is that even a word) we 
need to include the widest possible audience in discussions and a 
mailing list is the best possible resource for this (first one to say 
forums get's a slap ;-) )

The second is the mailing list archives are a reminder of why decisions 
where taken so we can move on from them.  If a decision is made on irc 
by a couple of people in a few months (when those people might not even 
be active anymore) no one can remember why the decision was made so it's 
impossible to comfortablly move on from mistakes.  Just my opinion but I 
have seen it happen in the past.

I love the community feeling of ubuntu.  As a passionate user of free 
software it's nice to be in a community that takes free software 
seriously and wants to move on without the constraints of some larger 
projects.  The way this doc team has been brought together is a credit 
to the 'ubuntu' of the project and the people it attracts, you should 
all be very proud of the work so far.


> 
> greets, AP
> 
> 
> 
> If you look at the SiteMap you can see there is structure is lacking
> in the wiki as it is today. Many parts of the wiki can not easily be
> reached nor found. We need a clearer structure and from that structure
> branch out. An example:
> 
> To get from FrontPage to BeagleHowto I would need to:
> 
> 1. Ah, a link called HowTo Guides, unfortunetely this page brings me to:
> 	http://ubuntuforums.org/forumdisplay.php?f=15
> 	http://www.ubuntulinux.org/support/documentation/howto
> that is not what i was looking for, back to FrontPage
> 2. Second attempt ... again a link to the ubuntuforums... Further down
> ... Finally burried between a bunch of other links the
> DocumentationArea, from there I can find the howto's. That was too
> dificult.
> 
> I have nothing against the forums, but the wiki is supposed to be a
> source of information not just a short link *out* of the wiki.

First my rant about the forums, I don't generally like forums but that's 
not my reason for thinking forums are currently not right for this 
project, at least unoffical forums at this stage of development.


I think the forums split the community.  I said this when they where 
first put together but as they provide a link to the mailing list 
(albeit a fucking annoying one sometimes) and people said this is 
something they want I let it go.  Everyone deserves access to infomation 
about ubuntu in a format that they find easiest to use if people prefer 
forums and the offical ones are still not here then the unoffical ones 
will do ;-)

But, today when exploring the issues raised by Ben I took a proper look 
around.  They have loads of questions and answers to stuff that had 
previously been discussed on the list and are just allowing a couple of 
so called 'gurus' to look good in front of the newbs ;-)  Not sure that 
directing people away from offical sources of information is a good idea 
when offical infomation is becoming such a high quality and easy to find.

I understand why they where created but now (to fill the gap while jdub 
(who I think was sorting the forums) was busy with warty.  Right now we 
should limit the amount of people we send there and attempt to cover all 
bases on the offical sites.

I am not saying ignore the site ;-) I think it should have a prominent 
link on the site because it *is* a part of the community.  The problem 
arises when people see it *as* the community and don't see that the 
mailing list (and other offical resources) have a far deeper reach.

Don't get me wrong here this is not me forgetting what ubuntu means ;-) 
it's me being concerned that the community is being split into a them 
and us thing at far to early a stage.
> 
> What do we need to do (on the new wiki) ?
>  1. we need priorities, what do we want to use the wiki for? in
> support you will see howto's and tutorials as well, why? what do the
> people who visit the wiki look at? can we somehow see that?

we can have a regular meeting on irc (but with the final aggrements on 
the mailing list to include the majority of the interested community) to 
approve priorities of the core team while respecting the rights of the 
community to develop things out of order ;-)  The ubuntu

The wiki is a great way to get others involved and we need to be 
flexible in the way it grows.  It really needs to be a central 
repository of information.  The restructed text thing will make it 
really easy to use the repository as a development aid for more than the 
standard wiki type docs, the whole documentation can be developed in the 
wiki and reused where ever is required later.

>  2. Bring structure in the wiki (see further down)
>  3. Make good templates for the creating of new Howto's so they look
> more or less the same. (Does plone support that???)

The look of the information is just a style sheet.  It's more important 
that the structure is good and strong from day one.

> 
> 
> Some ideas on structure in the wiki:
> 
> http://www.ubuntulinux.org/support/documentation/helpcenter_view has a
> nice structure. We could use something like that. We would get a page
> looking like:
> 
> ----beginning-of-page-----
> Ubuntu wiki
> 
> 1st paragraph. Introduction, what is wiki, what is ubuntu etc , etc,
> text text text etc

what is wiki, what is ubuntu etc, etc all need to be separate 
paragraphs.  One of the most important rules in writing technical 
english is keeping to the point, something I stuggle with at times, and 
writing the most simple way possible for the topic and audience.

Not picking faults here just nit picking ;-)
> 
> 2nd paragraph of intro, more text. and even more.
> 
> SiteMap:
> 
> Documents ->
>      Development (this would be links, with an explanation)
>      Errata      (idem dito)
>      FAQs        (also here)
>      Glossary    (well, you get the idea)
>      How-Tos     (...)
>      Places to find technical support 
>      Security Notices
>      Tutorials
>      Ubuntu Document Writing Guidelines
>      Ubuntu Teams 
> 
> End-notes, some more text. And more text. And a picture :)
> ------end-of-page-------
> 
>>From here it would be easy to make sub-pages eg the Howto page:
> 
> ----beginning-of-page-----
> Ubuntu Howto's
> 
> Applications Howto's       (a link)
> Installation Howto's       (one more link)
> Kernel Howto's             (...)
> Even more specific Howto's (...)

plus links to external how-to's when a ubuntu how-to is not required. 
It's better to work with existing how-to writers and provide a chapter 
(or a few paragraphs here and there) and link to the existing resource 
that reinvent the wheel.  Again it's something that's obvious but we 
will find ourselves doing this from time to time and need to stop each 
other from doing it.
> 
> Search Howto's: [          ]
> 
> List of ALL Howto's (a link)
> ->How to add you own Howto (a link)
> ------end-of-page-------
> 
> All main groups could have a frontpage like the one above, from there
> it would be easy to find what you need.
> 

As I pointed out on the users list a few days back the information 
architecture of the wiki is as important as the data.  I think this is 
an excellent start and shows we are thinking in the correct way (at 
least I think we are, I reserve the right to say we are all tossers and 
have wasted our time when I am feeling moody at some point :-P )

sparkes
-- 
<davee> "Sparkes, the Pete Best of LugRadio"