Wiki?

Mork II · 2004-02-02 22:01:12

The documentation of Arch is lagging behind a bit. Since it is difficult for one person to keep the docs up to date (or keep motivated to make that effort) it might be better if the docs could be maintained by the community.

So how about setting up an Arch Wiki?

There are as usual several open source software solutions available. There is at least one written in PHP.

contrasutra · 2004-02-02 23:48:29

I think that's a great idea. I would definitely help.

Also, it doesn't force people to learn any "odd" typesetting languages.

rasat · 2004-02-03 05:07:05

I would like to see Wiki becoming a common practice in Arch Linux. Not only in this forum where I registered a common username "wiki" for anyone to login and collaborate on wiki topics (few are already posted), but in AL's developments / projects as well.

Example wiki topic:
http://bbs.archlinux.org/viewtopic.php?id=2409

Only recently I was aware of this Wiki concept but its has been on Internet a quite long time and different distros and developers are starting to use it. Arch Linux should definitely start using Wiki.

Dusty · 2004-02-03 05:08:19

There is a wiki user in the forum, have you seen this?:

http://bbs.archlinux.org/viewtopic.php?id=2243
http://bbs.archlinux.org/viewtopic.php?id=2250

It was rasat's idea.

A full wiki might be helpful though too, to get all the docs in one place. My experience with them has been that they don't get edited much; I thought having them in the forum might make them more accessible to people... maybe there could be two versions so that people can copy "temporary" forum wiki to a more permanent full wiki page when documents become "useful enough"

Dusty

Moo-Crumpus · 2004-02-03 07:41:46

A wiki would be a great idea.

But we should care for quality. We should have a procedure. Maybe like this:

- First, post a solution in the Documentation forum. Let's vote for it, if it works or not. Let us find out if the solution is the best out of many options.

- Let us count "Yes" votes. If the votes exceese the limit, we will take it as a proof of quality. I don't know how strong the community is. Will a limit of 15 votes be to high? What do you think?

- After a solution has proven its quality, let us work on the text, and post it to a wiki administrator, with a suggestion where it could be placed.

- We may have an index first, and then seperate our forces on filling it.
Most common features are base install, tweaking, mouse and keyboard setup, setting language environments, add usb storage, digikam, mutlimedia, burning cd. Then, there should be a server part. How to make arch be a linux server, a samba server, a http server, a database server.

What do you think? I suppose users can take their part, they are currently working on, discuss their solutions. We would have a working docu very fast.

rasat · 2004-02-04 03:49:03

Quoted from:
http://bbs.archlinux.org/viewtopic.php?id=2185

rayzorblayde wrote:

i've read the "installation and first steps" guide in the documentation thing, but it isn't really a walkthrough step by step giving complete examples...

When speaking about documentation for any software, a walkthrough step by step giving example is the key. Its nice to learn what a program does, but if you don't know how to install then ....:(

Documentation is not only to provide knowledge but also the application (how-to-do). In this reagard Gentoo doc does well.

PS.
Beside Arch Linux doumentation, I am looking forward to find docs similar to the "Installing and configuring Apache, PHP, and MySQL" topic:
http://bbs.archlinux.org/viewtopic.php?id=2409

There are other frequently asked topics like Alsa, NVIdia and ATI what could be good to make into a walkthrough step by step wiki doc. Myself, I don't know the configure when not using them. But if someone types the base, I am ready to help.

Dusty · 2004-02-04 04:08:59

Puting "quality control" on a wiki kind of defeats the purpose. THe idea is that if documentation is low quality you can fix it.

On the other hand, it might be neat to have a separate area for mature versus draft documents...

I'm going to be messing with alsa next week, I think. I'll try to document it... or curse it.

Dusty

sarah31 · 2004-02-04 05:03:34

having format rules never hurts. personally i will not give any time or heed to docs that make my eyes hurt or head spin. ther eshould be a standard format and each doc should be as clear as possible, free of grammar and spelling errors and so forth.

as much as good docs help bad docs can drive away people. (bad can mean poorly written, non descript, or too verbose (for example gentoo can be too verbose and sorcerer linux used to have an install doc that was very devoid of good formatting which frankly turned me off of it)

rasat · 2004-02-04 09:50:20

sarah31 wrote:

personally i will not give any time or heed to docs that make my eyes hurt or head spin. ther eshould be a standard format and each doc should be as clear as possible, free of grammar and spelling errors and so forth.

With the Wiki system we may get quality product. When a group of members collaborate, the task will not depend on one person's skill and knowledge.

chane · 2004-02-04 13:24:02

Dusty wrote:

On the other hand, it might be neat to have a separate area for mature versus draft documents...

A wiki is a great idea and one with different areas is even better. An example site that I really like is www.hibernate.org. They have setup an easy/clean look with in essence two types of areas. 1 is an area that anyone can contribute anything (last one in the menu on the left). The rest of the site conforms to a certain level of maturity (content and L&F) of the documents. Also, as a document maturies the developers (or authorized users) will "promote" a document out of the community area into the main wiki, or maybe even the formal documentation...

I have a feeling that the wiki application selected will be very important. Any one have thoughts on which one to use?

Chris....

Moo-Crumpus · 2004-02-04 15:16:19

Sounds very good, fits every needs, as far as I can see.

Dusty · 2004-02-04 15:42:14

Such a setup gets my vote too. But who has both access to set it up on archlinux.org and the time to do so?

Sarah31: Having format rules *can* hurt. If people would write something but are turned off by having to format it "just so" they won't do it, and the document is lost. On the other hand, if they write it and the formatting sucks, somebody else can edit it per the Wiki to make it look better and grammatically correct.

Might I suggest "formatting guidelines" instead?

Dusty

sarah31 · 2004-02-04 16:25:43

feh why do i even bother validating myself to you. you want docs that look like shit go ahead. standards are the mean not an exception. if people are turned off by the standards and don't want to contribute then they should not even bother considring themselve part of the community. do YOU want to spend several hours correcting and styling up somebody else's work?

there is a standard accepted packaging format therer should be a standard doc format. otherwise you are offloading more work onto the developers. running spell checkers and putting your ideas clearly down "on paper" is not that hard a task.

the formatting i am talking about is putting your work in paragraphs and for step by step instructions to be put in bullet or numbered format for each step and not run two steps together on one line. it is not hard work nor is it too much to ask to make your doc look like this . would you want to clean something like this . while it is nicely formatted gramatically the clear breaks between catagories or steps, lack of headers for the different topic make this a hard to read catagory and the length discourages another user from editing it. manolis could have made a few tweaks as he was going along before commiting this final doc to this webpage.

the idea with standards is to have a functioning doc to start with not have sort of functioning eyesore. everyone like to make a big deal about gentoo's docs. they are good because they all follow a standard format.

Dusty · 2004-02-04 17:15:08

sarah31 wrote:

feh why do i even bother validating myself to you.

Ditto

sarah31 wrote:

you want docs that look like shit go ahead.

Of course I don't want docs that look like shit. I put a lot of care into the look of anything I write, be it a howto, source code, e-mail, or forum posting. Maybe not enough, but I do my best.

However, in some cases, semi-readable docs are better than none at all. (Unreadable docs are, as you said, not better than none at all).

Sarah31 wrote:

do YOU want to spend several hours correcting and styling up somebody else's work?

Can I hedge on that question? I'd rather not have to correct somebody else's style, no. On the other hand, I'd rather spend several hours cleaning up somebody else's work than spending several days writing a document from scratch AND cleaning up my own work.

Sarah31 wrote:

the formatting i am talking about is putting your work in paragraphs and for step by step instructions...

There's part of our misunderstanding then... I was thinking more about grammar and the like. It doesn't take a person any extra time to insert a newline between steps, so I'd hope they'd take the time to do it. (ie: I am not disagreeing with you!).

I was thinking more about people who maybe know English as a second language and aren't fluent with it. In that case, I'd be happy to clean up their grammar for them, as long as they did their best in the first place.

Dusty

rasat · 2004-02-04 21:17:56

I downloaded the PhpWiki and did few tests. Looks interesting.

1. When you edit a page one new version (page) is auto created. With "diff" function you can check the difference between the old and new. With a tag in "This is a minor change" blocks the auto funtion.

2. The administrator can lock and unlock pages. Remove, restore and backup.

3. All pages are linked. Instead of writing one long page, it can be divided into shorter pages linked to the main page.... authors can work on different subjects / pages at the same time.

4. To check what's new , press the "Recent Changes".

Screenshot:
http://phpwiki.sourceforge.net/phpwiki/

chane · 2004-02-05 01:40:50

rasat wrote:

I downloaded the PhpWiki and did few tests. Looks interesting.

If your using PHP, you might want to check out http://www.develnet.org/.

Most wiki's have the same basic functionality. While the one thing about most wiki's I dislike is the automatic generation of new pages based on WikiWords (basically, a variation of CamelCase depending on the wiki). With technical documentation, there are lots of times when I use CamelCase words that I really don't want to point to a page. It's a nit, but I dislike it enough to mention it in the formation stage...

I think any wiki is good and I'm not really concerned about which wiki will be used (particularly since it won't be my call to install/maintain). But as a potential user I mention this particular wiki, on the off chance you/someone who will install it wants to evaluate different systems (even briefly).

Chris....

Mork II · 2004-02-05 09:37:20

Pink Chick wrote:

But we should care for quality. We should have a procedure.

Quality is important, but I agree with Dusty:

Dusty wrote:

Puting "quality control" on a wiki kind of defeats the purpose. THe idea is that if documentation is low quality you can fix it.

Still there needs to be some kind of high quality documents. I can see three ways to do this:
1) As suggested: A wiki with a separate quality section
2) Keeping the main documentation in latex and letting the documentation maintainer take his/her pick of what to include
3) Providing links to authorities posting in the forums

Chane wrote:

If your using PHP, you might want to check out http://www.develnet.org/.

coWiki has support for all the needed formatting, but I can see two problems:
1) Syntax is not consistent. In a few cases you have to use nested tags (html-type) instead of shorthand symbols (PhpWiki does this as well). That makes it harder to write.
2) Another downside is that it uses html4 and tables. In my opinion tables should not be used for formatting whole pages, since that will cause acessability problems.

Chane wrote:

An example site that I really like is www.hibernate.org.[/url]

I agree that it looks good and the functionalty with the different sections seems really useful. It also loads really fast. The drawbacks are that it uses tables and that it's java. Now I'm not bashing java here, but seeing that archlinux.org uses PHP for pretty much everything I figured that should be easier to set up.

I prefer TipiWiki, also in PHP.
It has simple syntax, uses xhtml (allthough not correct), doesn't use tables and supports stylesheets (that makes it looks easy to customise). However there are (again) two drawbacks:
1) It uses ! before words to get headers. This might be a limitation while writing in spanish.
2) It doesn't have support for anything like the pre-tag in html. That makes it almost impossible to supply code examples without them getting wikified.

rasat · 2004-02-08 05:20:22

I have made one temporary / demo Arch Wiki on my server for Archers to have an idea how it looks. With the demo setup, I am seeing both user and developer contributions can benefit by the Wiki system.
http://bliss-solutions.org/archlinux/wi … p/HomePage

Note: If the page doesn't display poperly (there is an error), click "PHP Wiki" icon at the right upper corner.

morphus · 2004-02-08 08:24:03

I have made one temporary / demo Arch Wiki on my server for Archers to have an idea how it looks. With the demo setup, I am seeing both user and developer contributions can benefit by the Wiki system.
http://bliss-solutions.org/archlinux/wi … p/HomePage

This is definetly awesome. It is so easy to edit / create pages on different subjects without the need to learn any kind of special language.
About the quality and rules: There should be some guidelines how to create new sites and edit other sites, but none of them should be like "if you don`t edit this site this way, your page will be removed immediatly". The big advantage is that ANY user who is browsing the wiki can edit it. If I browse any wiki for any information and I see a Typo I just edit the site and fix it. There is no need for people just watching new created sites and fixing all typos and stuff like that.

Just look at www.wikipedia.com . They have Guide Lines about how to edit sites, but if someone doesn`t use them, there are other guys who will correct them. And the Quality of wikipedia is awesome.

Really good documentation by someone who is in charge of it is better than any wiki. But since there are not so many people around here who would really like to do a full-time-job with creating and updating arch`s documentation, we should give the wiki a try.

sarah31 · 2004-02-08 08:45:10

any wiki that the community wants should be officially hosted by arch linux. this would allow for a easier flow from first appearnce to being put in the official docs.

Dusty · 2004-02-09 19:38:24

sarah31 wrote:

any wiki that the community wants should be officially hosted by arch linux. this would allow for a easier flow from first appearnce to being put in the official docs.

Most certainly.

Who has access to do that, and why haven't they posted to say "great idea, I'll get right on it"?

Dusty

Xentac · 2004-02-09 20:02:14

Judd does, and he hasn't posted because we're looking into decumentation methods right now (see the newsletter).

Arch Linux

#1 2004-02-02 22:01:12

Wiki?

#2 2004-02-02 23:48:29

Re: Wiki?

#3 2004-02-03 05:07:05

Re: Wiki?

#4 2004-02-03 05:08:19

Re: Wiki?

#5 2004-02-03 07:41:46

Re: Wiki?

#6 2004-02-04 03:49:03

Re: Wiki?

#7 2004-02-04 04:08:59

Re: Wiki?

#8 2004-02-04 05:03:34

Re: Wiki?

#9 2004-02-04 09:50:20

Re: Wiki?

#10 2004-02-04 13:24:02

Re: Wiki?

#11 2004-02-04 15:16:19

Re: Wiki?

#12 2004-02-04 15:42:14

Re: Wiki?

#13 2004-02-04 16:25:43

Re: Wiki?

#14 2004-02-04 17:15:08

Re: Wiki?

#15 2004-02-04 21:17:56

Re: Wiki?

#16 2004-02-05 01:40:50

Re: Wiki?

#17 2004-02-05 09:37:20

Re: Wiki?

#18 2004-02-08 05:20:22

Re: Wiki?

#19 2004-02-08 08:24:03

Re: Wiki?

#20 2004-02-08 08:45:10

Re: Wiki?

#21 2004-02-09 19:38:24

Re: Wiki?

#22 2004-02-09 20:02:14

Re: Wiki?

Board footer