2004-02-09T20:02:14ZFluxBBhttps://bbs.archlinux.org/viewtopic.php?id=2421Judd does, and he hasn't posted because we're looking into decumentation methods right now (see the newsletter).]]>https://bbs.archlinux.org/profile.php?id=1452004-02-09T20:02:14Zhttps://bbs.archlinux.org/viewtopic.php?pid=14015#p14015sarah31 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

]]>https://bbs.archlinux.org/profile.php?id=7042004-02-09T19:38:24Zhttps://bbs.archlinux.org/viewtopic.php?pid=14012#p14012any 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.]]>https://bbs.archlinux.org/profile.php?id=202004-02-08T08:45:10Zhttps://bbs.archlinux.org/viewtopic.php?pid=13901#p13901

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.

]]>https://bbs.archlinux.org/profile.php?id=3422004-02-08T08:24:03Zhttps://bbs.archlinux.org/viewtopic.php?pid=13898#p13898I 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.

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

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.

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....

]]>https://bbs.archlinux.org/profile.php?id=5772004-02-05T01:40:50Zhttps://bbs.archlinux.org/viewtopic.php?pid=13635#p13635I 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.

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

]]>https://bbs.archlinux.org/profile.php?id=7042004-02-04T17:15:08Zhttps://bbs.archlinux.org/viewtopic.php?pid=13604#p13604feh 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.

]]>https://bbs.archlinux.org/profile.php?id=202004-02-04T16:25:43Zhttps://bbs.archlinux.org/viewtopic.php?pid=13600#p13600Such 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

]]>https://bbs.archlinux.org/profile.php?id=7042004-02-04T15:42:14Zhttps://bbs.archlinux.org/viewtopic.php?pid=13596#p13596Sounds very good, fits every needs, as far as I can see.]]>https://bbs.archlinux.org/profile.php?id=5742004-02-04T15:16:19Zhttps://bbs.archlinux.org/viewtopic.php?pid=13594#p13594Dusty 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?

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.

]]>https://bbs.archlinux.org/profile.php?id=1182004-02-04T09:50:20Zhttps://bbs.archlinux.org/viewtopic.php?pid=13577#p13577having 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)