Documentation discussion

[imnotpc]

There have been a couple of suggestions regarding the naming and placement of documentation on the site. In summary: Someone suggested a main menu item "Use It", I suggested a main menu item "Documentation", and Tuukka added an "Instructions" link to the main page which I've added to. Here are my thoughts...

1. At this point I think a main menu link to "Users", "Use It", or something similar, is better than a link to a "Documentation" page. There's a nice progression and flow to: See It, Download It, Use It, Discuss It, Develop It.

2. Following this theme, I think there should be a separate users and developers documentation sections. There is little or no overlap and I think grouping sections based on the individual's level of involvement makes a more efficient site layout.

3. For the documentation section I prefer grouping links in a table rather than a multi-level wiki outline. This creates an easy way to see all the links at once for easier navigation. Alternately, listing in wiki outline format will require quite a bit of scrolling once we have more content and having a TOC that simply brings you to a link is kind of pointless.

4. At some point we ought to consider creating a main page with a full featured content management system in place. Somewhere for news about new releases, plugins, and other news and announcements. David stated on the mailing list that he was interested in someone to manage the site. According to his post, anyone interested should contact him.

Discussion...

[amgeex]

I agree with your statements imnotpc. I have a good amount of experience managing content management systems, I could help set the site up and manage it. I think that we should make a poll to choose the cms, because I guess everyone would want one that they like, can work with etc. What do you think of this?

[imnotpc]

Sure. Just for the record I prefer exponent or joomla for cms. I like exponent for the easy editing and templates that are html, php, and css without tables. Joomla has a lot more modules and is more mature with a larger user base, however their standard templates are pretty easy to spot and designing a new template takes some effort.

[amgeex]

Alright, sounds good. I've used Joomla before, although its not my cup of tea. I'll check Exponent out, sounds nice. :D

[RYX]

Concerning the content (1.-3.) I fully agree with you, imnotpc. And for 4. I have some additions:

+1 for joomla

Why? I have been a web-/multimedia-dev for some years now and I recently had a first contact with joomla (before I prefered hand-coding in PHP). I find it really useful and simple to setup and manage (though strange at the first glance). I never used a wiki myself, so I cannot really say what is possible with a wiki and what is not. Some reasons for using joomla:
- we could easily create a multi-language site (I could translate to german)
- many components available which could be helpful for community-based things as well as distributed development
- whoever wants an editor-account could ask on the forums, express the reason why he wants an account e.g. for translating content and then be granted or not (to avoid wiki-spamming)
- easy theming-abilities (=better extensibility)

So I think we should first try to discuss and decide which CMS we want to use ... (and how David thinks about moving from wiki-style to cms).

:)

[imnotpc]

I've got a little somewhat OT story about Exponent. A few months ago my son got a gig re-designing a windows base site that needed a better cms. Being an teenager with way too much time on his hands, he downloaded and installed *every* cms he could find. I think he ended up trying out about 20 before he was done. He decided that Exponent was the best designed of the bunch but was a bit buggy and light on features. So now he spends every (non-working) waking moment hacking their code and adding features.

I'd be interested to hear what others think of Exponent. Is it worth his time, or do I need to kick him in the butt and tell him to go get a job! <grin>

[mikedee]

I personally do not think we will have a chance of changing the cms :)

Really the content is the most important thing, if we can work something out on the forums (or on a seperate html page), someone should be able to convert it to the dreaded wiki code.

I think Use it would be the best and it should have a brief introduction to using compiz. There would be a quick explanation of the plugin system and how you can add or remove them. There should be a brief overview of each plugin and what they do, the plugins could be broken down into 3 groups, essential (compiz will not work right without them), recommended and bling. The quick table would link to a more detailed plugin page with tips and configuration information. There could also be links to various howtos (eg, adding a skydome image etc).

[RYX]

I think the biggest problem of open-source and free-software projects in general is the missing (or "glance-less") self-presentation. There are some kickass-apps out there which have so disgusting websites that it hurts. If you want to attract someone to try and/or use something, you need to present it right. Compiz is currently being presented in a totally unacceptable way. We immediately need to create a better design and logo for the page, otherwise compiz only scares away users with a professional attitude ...

So is there a way to make the wiki multi-language and themeable (or at least a way to give it something you can call "design")?

@imnotpc: I have never used exponent, but I will have a look at it ... :)

[mikedee]

So is there a way to make the wiki multi-language and themeable (or at least a way to give it something you can call "design")?

I think this is something that will come in time, hopefully if we can add a lot of information we could convince David to accept the 'box' later on. I think multiple languages is possible, but the page naming scheme needs to be clearly thought out, maybe look at wikipedia to see how they acheive it.

Remember we are still in the early days, in my opinion getting the content up should be the priority. Nice graphics and images can be added within the wiki code which can hopefully help with the user friendliness.

The benefit of wiki is that it is at least a standard, all the other cms tools seem to use their own way of doing things. Wiki may be hard to edit but at least it is standard and there will be a lot of people who do understand it.

[RYX]

Yes, you're right in that content is more important than design. But the Joomla-CMS really offers a lot of flexibility and features. It is totally standard-conform, since it uses CSS for the templates and the content can easily be added and categorized even .

I think a wiki results in total chaos and ugly formatted texts, a cms would allow concentrating on the content while keeping the layout separated. Different users could work on layout and content without problems.

Of course we need to focus on the contents first, but now we still have the ability to switch to a cms, if more content is added this will get more and more difficult. So maybe we should ask David about that (and make a poll if he confirms) ...

:)

[imnotpc]

@ mikedee: I hope David will see the benefit of what we want to do and support it. In the short time I've been here he's been active and supportive of the "new" community.

@ RYX: I agree 100%. Most open source projects that I'm involved in revolve around one or more exceptional coders with little or no interest in presentation or documentation. Unfortunately that means the projects never achieve more than enthusiast level support. There's a lot of components needed to make a successful project, but in addition to a great code base a high quality web page, a friendly user community, and good documentation are essential.

[amgeex]

I agree on the presentation issue. We should have a very nice, but functional, website. It should be appealing to new Compiz users, it should be easy to navigate and to find what you're looking for. A great design always helps.

On the joomla territory, I'm not sure I agree 100%. I think joomla is too much for our needs, as it has a bazillion of modules and what-not that we, probably, won't use. It's easy, that's a given, but what about other cms's like Drupal?

Also, I think a wiki is a very nice system for documentation, as it is clean and minimalistic, so I think we should analyze the possibility of keeping the wiki for all documentation, or at least check out other wiki solutions. I volunteer to fix formating issues on the wiki, I don't mind doing it.

EDIT: Mediawiki IS customizable, check this link out. (http://meta.wikimedia.org/wiki/Gallery_of_user_styles)

[imnotpc]

I'm kind of agnostic when it comes to wikis. On one hand I'm annoyed by yet another quirky markup language to learn, yet I see the advantage of getting the users involved in the project and the benefit of their contributions. As long as the leaders in the community keep the wikis from getting out of control I'm OK with it, although I do think that important documents need to be protected from random edits.

[RYX]

Only to note: The mediawiki supports multi-languages by using a 3rd-party extension and has skin-support ... but I still vote for joomla :)

[FunkyM]

The Wiki is exactly what meets the current requirements and especially enables anyone to edit it's (still lack of) content. Using a CMS which is always limited to maintainers is totally useless at this stage.

If you note that you do not have much experience with (Media-)Wiki please try to get some further information to be able to compare it properly to other systems. Mediawiki is a very extensible and configurable system on the backend and a very userfriendly collaborative system on the frontend that is totally sufficient for now.

You have to add further Documentation sections to the Wiki and invest some (minor) time to learn how to work with it which is going to solve all issues and enable anyone with ideas to directly drop in without asking for CMS editing permissions...

[amgeex]

I guess FunkyM is right. I'm backing up his position on this issue. I too believe the Wiki is a must for documentation, as its very easy to use. I think that someone must be in charge of maintaining the wiki so we can keep it ordered and well written.

[RYX]

Ok, I am a little upset ... the following sounds more angry than I actually am ...

I am kind of disappointed (but in no way surprised) that the "real" devs are totally ignoring any good arguments ... (I mean the mailing list, nobody in this thread). What does a project need a good website for? ... of course ... for nothing ... who needs a website at all? Why don't we just upload some text-files where everyone can get the information he wants ... seems to be enough for developers - so it is definetly enough for end-users, hmm? ... A good website and presentation is what made projects like blender as successful as they are ... end-users like eye-candy as much as devs like text-files!

1. I wouldn't even dare to call the current situation a "theme" or "design"
2. I never said wiki-code is difficult, calling it "code" is somehow ridiculous
3. I already mentioned the multi-language capabilites of a wiki, but a cms comes with pre-translated parts and support for multi-language without using half-assed workarounds
4. I am not _afraid_ of wiki-spamming, I am a realist and don't close my eyes in front of the real problems to ignore them - wiki-spamming is existent ... we should be aware of it.

A wiki is for documenting, not for creating entire websites with it .... (yes it is possible ... do you code gtk-programs in assembler only because it is possible?) ... If you want to do things the "Novell way" (like go-mono.com) ... do so, but without me ...

:x

[amgeex]

Well, I definitely think that we should set up a proper website. We shouldn't be arguing about whether or not we should replace the wiki with a cms, we should be discussing the cms options that we have and choose one to start work on the site.

I guess that it'd be best if the forum and the main (non-wiki) website had a unified look. We'll need the help from someone sharp in the graphics department. I already volunteered to help setting the cms up, as I've got some experience managing those.

Any more volunteers?

[RYX]

Sorry for being a little rude ... wasn't adressed to anyone directly. I offer my help in creating, designing and managing the website/cms.

[imnotpc]

RYX, I feel your frustration. There's so much more that could be done with very little effort. Just be patient and keep contributing the way you have. Hopefully David will answer my posts on the mailing list and let us know his opinion/decision.

On a related topic, the compiz.org domain name has officially been transferred to David (or his designee). David indicated this site would move to compiz.org, but since they are hosted by the same people it shouldn't be an issue. My thanks to Guillaume for being a standup guy and following through.

[mikedee]

So it looks like David is happy for you guys to do whatever you feel is necessary.

Please though, can we try to plan an overall view of how the documentation will work and then work on the individual parts.

There are 2 sides to the documentation, users and developers at the moment they seem to combine a little bit. I have done a little on the wiki to remove git instructions and compiling from git out of the users section. I have also put together a quick page listiong the plugins and what they do. Users really should either install their distros version or they should compile from a release, this will help supporting it.

A lot of what needs doing is putting down FAQ's etc and howtos for each brand of card. My feeling is that there should be 3 basic sections for the user which should each be no longer than 2 screens high (ideally). They should be something like installing running and using. These as far as I can see are the main obstacles that you must cross before you are one of the enlightened ones.

If each of these sections could be short and to the point with most cases covered then it will be ideal. We can also avoid a lot of support questions by providing some sort of checklist where they can check their setup is correct at each stage (this will also help if they do have problems as we can see where the problem is)

[amgeex]

OK, so we've been green lit to set up the cms. The question is, are we keeping the wiki for documentation, or are we going to move everything to the cms?

[mikedee]

Could we have a quick run down of all the pros and cons of each different cms and then take a quick vote on it. Ideally someone could be chosen to be the dictator but we need to make sure that all of the pros and cons of each system are identified.

I am worried about things like maintainability and security in particular, I know from experience that a lot of these cms's are highly complex and often written without concideration for security. Look at the problems with phpbb, if there is an upgrade to the core then all of the custom design is wiped out because there is not a proper template system.

I am slightly clueless about the pros and cons of each so at the moment I would prefer to stay with wiki because that is more of a known quantity (to me anyway). I am sure that there are many opinions on which one we should use, but ultimatly the decision should be made on which best fulfils our needs. Ease of maintainability (both content and server side) is very important in my book.

[amgeex]

I agree with mikedee here. I would like to propose that we make a poll with several cms/wiki options and the first post should include detailed information about each cms/wiki's features, including ease of use, installation, maintenance, and security. 8)

Each one of us could vote on the cms he/she considers suits the project best, then we could discuss it and then we should make the final choice.

[imnotpc]

I agree

[amgeex]

Well, I was thinking about an easy way to compare different cms/wiki packages, and I remembered about cmsmatrix.com. Its a very straightforward site that we can use to compare different systems. It's got tons of systems listed, so it we are not lacking options.

Check it: http://www.cmsmatrix.org

[imnotpc]

Wow, there's a zillion of them (actually about 650, but still...)
My resident CMS expert also recommends this site: http://www.opensourcecms.com/
There's a demo menu on the left that lets you work on a live demo site. They also have a section for wikis so we can see all the options. And of course these are all opensource.

[RYX]

Though I really like "exotic" apps, I'd really recommend using Joomla (yes I know, I already did). It is the GPL'ed open-source descendant of Mambo (developed by one of Mambo's former leading developers) and won the "UK Linux Award" twice. It is among the top-ten of the most downloaded open-source apps in the world ... It would offer seamless integeration of wiki and forum by using so called "wrappers" or "bridge"-modules. We could keep everything as it is and only "glue" the site between the forum and the wiki. Said short: I recommend Joomla.

Please post your favorites here so I (or someone else) can create a poll with the most wanted CMSes - because I really don't want to list all 600+ choices in the poll ... (and want to avoid listing only my personal favorites).

:)

[imnotpc]

I use Joomla for a couple of small sites and I like it fine, but the one negative I have is that the standard templates already used on thousands of sites and developing a custom template is a real PITA. Do you have an available template in mind and/or are you willing to design one?

[RYX]

I'd say we could choose one template from the available ones and I modify it (or someone else, it's only an offer) to make it look unique ... it's really not that difficult. Coding a new template from scratch is quite stupid because basically 70% of the templates' code is the same for all. The more important part will be creating a good-looking logo for compiz and the site (or either choose the "cube" (this page) or the "splat" (go-compiz.org), which I don't really love both). Also we have to agree on a color-scheme ... (I think we should have another thread for that).

:)