Documentation Project for Arch [UPDATE]

iLLucionist · 2006-08-15 13:06:36

I read this topic about the popularity about Arch and it kept me thinking for a couple of weeks.

I'm really devoted to Arch and I'd like to start a professionally-aimed Documentation site for Arch Linux with an appropiate installation guide and other guides for installing X.Org, Servering, Desktop-stuff etc.

My question is: how would you feel about it? Anyone who wants to collaborate? Tips? Suggestions?

Upon your responses I will post my 'plan' with a concept lay-out and system based on your input and my thoughts within the next two weeks. I'm only able to do Dutch and English.

:arrow: [UPDATE #2: Contents]
Ok, I've taken notice of all your comments. Many thanks! However, I was wondering which categories "slash" manuals their should be. I was thinking about the following:

1. Guides
* [AInsG] Arch Installation Guide
Covers the Arch Installation from retrieving an ISO to the bash-prompt.
* [ADskG] Arch Desktop Guide
Covers the installation and configuration of software desktop users mostly use like: Gnome, KDE, Cups, Codecs, Gimp. Stuff like that. Installation from Bash Prompt to X.Org with software.

* [ASvrG] Arch Server Guide
Covers the installation and configuration of software that servers run, like: NTP, Apache, MySQL, PostegreSQL, PHP, FTP, SSH, etc.

* [APkgG] Arch Packaging and Maintenance Guide
Covers the deep internals of Pacman, ABS and buildpkg. How to maintain, update, install, make packages etc. What to do if things fail, etc.

* [AKnlG] Arch Kernel Compilation Guide
Discusses how to compile your own kernel. I think it just should be there for user convenience.

* [ADevG] Arch Developer Guide
Covers the installation of software developers use.

* [ASecG] Arch Security Guide[/i]
Learns the user how to secure your Arch installation thoroughly.

2. Categories
* Guides
Guides like I've listed above.

* Howto's
Maintained Howto's and a link to ArchWiki for unmaintained Howto's.

* Advisory
When you maintain a linux installation you come across many odds and weirds. Newcomers don't know these things cause they haven't experienced these odss and weirds yet. So we could place that here for convenience. For example: XFS works perfectly normal, but Grub may hang. Or the fact that on some systems Ati drivers are unstable. That kinda stuff.

* Community
References to other parts of Arch Linux, like the BBS, Wiki and Homepage and the policies for writing documentation etc.

Conclusion
So, this is what I come up with. What do you all think?

:arrow: [UPDATE #1: Why no wiki & quality notices]
I've taken notice of the first four posts and I have to make something clear. The wiki is not the way professional documention should be taken care of. I'm really thinking about a 'Documentation Project' rather than a dumpplace on the net where every moron can simply post his experiences. Just look at the wiki. Just look at it!

What I was thinking of is to build (Me, PHP/MySQL dev) an Arch Documentation webapplication (or deploy and customize an existing system) and form a project team consisting of a couple of really devoted people, including myself, to write and maintain documentation.

And if people have comments on the docs, they can discuss it at Arch BBS here, perhaps a new room for Arch Documentation Project?

In my opinion the quality of documentation should be highly improved and I don't think letting everyone collaborate is a good idea. Especially not if I look at the Arch Wiki.

:!: Oh, and one last note. I don't hate wiki or want it to disappear. I think there should be two places: one place for us all where we can freely collaborate (wiki) and one place (Arch Doc Project) where official and maintained docs are held.

So, any thoughts upon this? Let me know please. I'll keep on track.

soloport · 2006-08-15 13:28:23

It's good to have a plan. It's best to have good documentation. However, re-inventing the wheel is not so good. What I'm saying is, let's clean up the exisiting Wiki, not create yet-another-documentation-site. That's a plan I would gladly support.

My two cents. 8)

jaboua · 2006-08-15 15:20:09

Working on adding stuff to the wiki sounds good yes, as IMO it's better with one big documentation source than having to search multiple documentation pages (that is, the wiki and your documentation page)...

But if you think having seperate documentation sources is better (for example if you just want a simple guide through the basics to get people started instead of explaining everything going on behind the scenes, something that the wiki might do), nothing can stop you and I wish you luck

murffatksig · 2006-08-15 15:37:30

I would support anything that helps promote the advancement of Arch. If you want to set up your own documentation page, more power to ya.

arooaroo · 2006-08-15 16:17:54

Yeah, I think the Wiki needs expanding (and tidying up a bit).

Look on Newbies Corner - what are the FAQs?

And I think Cactus is the documentation guy for Arch. Anything you do ought to involve him.

Tatey · 2006-08-16 02:12:15

The advantage of having a documentation team is that its possible to enforce high standards and strict quality control. As a result, you cover important topics that are always up to date. The documentation can cover Arch, GNOME, KDE and Other WM's installations as well as other guides relating to the ABS and managing your Arch install. This falls under the category of "Official Documentation".

In contrast, I think its important to maintain a separate wiki where members of the community are free to contribute. A documentation team could NOT keep up with every possible guide. For documentation other than the "Official Doco" that I've described above, I think the Wiki is appropriate. Gentoo follows a similar model with their official documentation and a separate Gentoo-Wiki (Which is completely 3rd party AFAIK). Gentoo is renowned for its excellent documentation, and through a dedicated documentation team we may be able to produce a similar, or even better result.

This doesnt change the fact that the existing Wiki needs some cleaning up in areas. I'd also propose a "Standard" of how Wiki's should be layed out, and an example of a "Good" and "Bad" entry. In addition, you'd need a watchdog to issue quality notices where appropriate.

I'm no programmer, so I'd love to be able to contribute to the Arch community in some form, and documentation seems ideal for me. Therefore, I'm putting forward my interest in this project. I've always heard various other people complain about the documentation on Arch, and I think it's an appropriate step.

Dusty · 2006-08-16 04:16:26

I agree with most of what Tatey has said, but for useability, I suggest all documentation go in one place. I suggest that the "official" docs be wiki docs that are officially maintained by some group of dedicated enthusiasts, completely intermingled with unofficial docs that may or not be maintained. The restriction could be that official docs could only link to other official docs that are quality controlled, but of course, the unofficial ones could be added to the list of controlled documents at any time.

The beauty of this is that you don't need anyone's permission to do it.

Dusty

iLLucionist · 2006-08-16 12:26:58

Thanks for the response all! Being it quite sparse, it gives me enough to improve my thoughts upon.

Expect to see the following of me within the next couple of weeks:
:arrow: A convenient project plan (concept) covering everything I want to do.
:arrow: A webapp developped and hosted by me on which documentation can be built.

What I'd like to see from the community:
:arrow: People who like to help me, like Tatey. (writers, translators, maintainers)
:arrow: More input about how the community likes to see it.

Oh, and one last notice. Nowadays I have my own company in IT, Lucus consultancy (located in The Netherlands, www.lucuscon.nl). I'm also able to financially support this project for as far as it lies within my power.

Thanks so far! Great help.

tomk · 2006-08-16 12:53:59

A note of caution (possibly just me) - I don't think the word 'official' should be used, unless approval is sought and received from the Arch devs.

Dusty · 2006-08-16 15:21:32

tomk wrote:

A note of caution (possibly just me) - I don't think the word 'official' should be used, unless approval is sought and received from the Arch devs.

In fact, the correct word would be "unofficial". ;-) However, the best way to get approval from the devs is to do it right and then show you've done it. Too many people say "I'll do X" and never do it. If you do the project and do a good job, it'll get incorporated into Arch proper.

As a former Arch Linux Documentor, I'd like to direct you to the Arch Linux style guidelines...

BUT I can't find a link in the new web layout... very interesting, no wonder you're looking for more official docs; the ones we had are gone!

Dusty

dtw · 2006-08-16 15:39:35

They must be about because Iphitus used them to create the new guidelines for modules...oh, what do you know?! He put the guidelines for documentation in the root of his documentation! He's a smart lad that one.

http://archlinux.org/~james/module/docwriting/

I wonder if I should convert the CVS/SVN guidelines to a hallow doc? What about your Java stuff Dusty? Did you give up waving that at people to no avail..or do people just not pkg Java apps?

arooaroo · 2006-08-16 18:55:21

dtw wrote:

I wonder if I should convert the CVS/SVN guidelines to a hallow doc? What about your Java stuff Dusty? Did you give up waving that at people to no avail..or do people just not pkg Java apps?

http://wiki.archlinux.org/index.php/Jav … Guidelines

majikstreet · 2006-08-17 01:07:11

I think that Arch should have a documentation team that cleans up the wiki and maintains it. The wiki should continue to be open to all users, though.

Just my thoughts..

majikstreet

soloport · 2006-08-17 03:54:40

majikstreet wrote:

I think that Arch should have a documentation team that cleans up the wiki and maintains it. The wiki should continue to be open to all users, though.

What? No way. Won't happen. It's impossible to have a bonefide documentation site unless it's fully funded by an IT consultency. Didn't you read the notice?
.

Dusty · 2006-08-17 04:22:30

majikstreet wrote:

I think that Arch should have a documentation team that cleans up the wiki and maintains it. The wiki should continue to be open to all users, though.

Ideal solution. Its what Dennis and I decided on when we planned this all out, we converted some docs to wiki format and I spent a lot of time going through the wiki reworking the English and style to be consistent. But I don't think the current documentors on the dev team touch the wiki anymore. :-( But even so, a dedicated team of official OR unofficial wiki maintainers would probably be the greatest thing for Arch.

But I'll tell you right now, its a thankless job and nobody will really notice you're doing it. They'll only notice when you aren't doing it... like the current state of the wiki. The point I'm making is there's no reason the wiki can't be as polished and professional as some "closed" set of documents, except nobody's doing it.

Dusty

majikstreet · 2006-08-17 19:43:32

Then we need to gather up some people who are willing to do the job despite it being a thankless job. I'm sure that there are people who are totally willing to clean up the wiki without being thanked. I agree, the wiki can be as good as a closed set of documents. It can be better than a close set of documents because instead of have a few users writing docs, we have many users writing the docs and a few cleaning them up. It's better to have more not cleaned up (or dirty I guess) docs than not many clean docs, in my opinion of course.

majikstreet

Edit:
But I think that before we can start trying to clean up the docs, we need a set of guidelines. Once we have this set of guidelines for the wiki, we can have a dedicated group clean the wiki, and anybody who read the guidelines could help without having a commitment.

Dusty · 2006-08-17 20:29:38

majikstreet wrote:

But I think that before we can start trying to clean up the docs, we need a set of guidelines.

*Sigh* All my work is lost. :-/

I wrote a set of guidelines for the old wiki, but I'm pretty sure they got lost during the wiki migration, and they probably wouldn't apply to the new format anyway. So give it a go. I definately don't have time to join this team of dedicated unthanked documentors, but I really hope there are people who can, I'd like to see this for Arch.

Dusty

phrakture · 2006-08-17 20:40:19

iLLucionist wrote:

The wiki is not the way professional documention should be taken care of. I'm really thinking about a 'Documentation Project' rather than a dumpplace on the net where every moron can simply post his experiences. Just look at the wiki. Just look at it!

I abandoned all hope when reading this. Not only is the "wiki is not professional" outlook pretty outdated (Wikipedia anyone?), but there is the fact that suddenly a wiki is only edited by "morons".

majikstreet · 2006-08-17 21:08:59

Dusty wrote:

majikstreet wrote:
But I think that before we can start trying to clean up the docs, we need a set of guidelines.
*Sigh* All my work is lost. :-/
I wrote a set of guidelines for the old wiki, but I'm pretty sure they got lost during the wiki migration, and they probably wouldn't apply to the new format anyway. So give it a go. I definately don't have time to join this team of dedicated unthanked documentors, but I really hope there are people who can, I'd like to see this for Arch.
Dusty

Are these guidelines included in http://archlinux.org/~james/module/docw … guide.html ?

I suppose we could adapt that for the wiki.

majikstreet · 2006-08-17 21:10:18

phrakture wrote:

I abandoned all hope when reading this. Not only is the "wiki is not professional" outlook pretty outdated (Wikipedia anyone?), but there is the fact that suddenly a wiki is only edited by "morons".

This seems to be the mentality in the arch doc guidelines too,

To remedy the lack of organization somewhat, the ArchWiki has been set up to structurize available guides, questions and howtos, and put them under constant public supervision. Although being proof-read by potentially dozens of people, the information is still not authoritive in any way; Anyone can add and modify anything in the wiki, which is not acceptable for documents intended as reference.

edit: I think we should base the guidelines on the format that cactus' wiki pages tend to use (eg http://wiki.archlinux.org/index.php/PostFix_Howto) They seem to explain the topic in detail and provide a lot of information about the topic and what the goals of the howto are.

soloport · 2006-08-17 21:32:47

phrakture wrote:

I abandoned all hope when reading this. Not only is the "wiki is not professional" outlook pretty outdated (Wikipedia anyone?), but there is the fact that suddenly a wiki is only edited by "morons".

So, you weren't persuaded by the, "I'm also able to financially support this project for as far as it lies within my power."?

Speaks volumes (pardon the pun).
.

Arch Linux

#1 2006-08-15 13:06:36

Documentation Project for Arch [UPDATE]

#2 2006-08-15 13:28:23

Re: Documentation Project for Arch [UPDATE]

#3 2006-08-15 15:20:09

Re: Documentation Project for Arch [UPDATE]

#4 2006-08-15 15:37:30

Re: Documentation Project for Arch [UPDATE]

#5 2006-08-15 16:17:54

Re: Documentation Project for Arch [UPDATE]

#6 2006-08-16 02:12:15

Re: Documentation Project for Arch [UPDATE]

#7 2006-08-16 04:16:26

Re: Documentation Project for Arch [UPDATE]

#8 2006-08-16 12:26:58

Re: Documentation Project for Arch [UPDATE]

#9 2006-08-16 12:53:59

Re: Documentation Project for Arch [UPDATE]

#10 2006-08-16 15:21:32

Re: Documentation Project for Arch [UPDATE]

#11 2006-08-16 15:39:35

Re: Documentation Project for Arch [UPDATE]

#12 2006-08-16 18:55:21

Re: Documentation Project for Arch [UPDATE]

#13 2006-08-17 01:07:11

Re: Documentation Project for Arch [UPDATE]

#14 2006-08-17 03:54:40

Re: Documentation Project for Arch [UPDATE]

#15 2006-08-17 04:22:30

Re: Documentation Project for Arch [UPDATE]

#16 2006-08-17 19:43:32

Re: Documentation Project for Arch [UPDATE]

#17 2006-08-17 20:29:38

Re: Documentation Project for Arch [UPDATE]

#18 2006-08-17 20:40:19

Re: Documentation Project for Arch [UPDATE]

#19 2006-08-17 21:08:59

Re: Documentation Project for Arch [UPDATE]

#20 2006-08-17 21:10:18

Re: Documentation Project for Arch [UPDATE]

#21 2006-08-17 21:32:47

Re: Documentation Project for Arch [UPDATE]

Board footer