complete arch (system) documentation?

pelle.k · 2007-04-04 16:12:13

Hi. I would like to have arch and it's mechanisms and infrastructure completely documented. Of course this could be quite a large task, but i think people like me (who like to read the manual before using stuff) would appreciate this, and it would also serve to leverage the overall knowledge of archlinux, so that less people would ask "stupid questions" (i don't mean it like that.. ) on the forums.
I also understand that this could realistically only be done for a "base" install arch system, as X11 and other applications/services go beyond the scope of such basic documentation.

The reason i would like this is because i couldn't find anything like this on the wiki, _and_, it would also be nice to have something compiled in a form you could print out. (ie without further references, but a compilation).

cactus · 2007-04-04 16:40:35

I think this is a wonderful idea.
Documentation is a hard thing to get people motivated to create though.

Documentation is weird like that.
People love using it.
People hate not having it.
People get excited when they use great examples of it.
People are sad when they have bad examples of it.
People generally loathe creating it themselves.

Arch has the infrastructure to get this accomplished (wiki).
If you can get people motivated to work on it, that would rock.

Weeks · 2007-04-04 20:03:25

I agree that this is a great idea. A FreeBSD type manual would be awesome.

There are some slight problem with our rolling-release mechanism, but that could be circumvented by adequate explanations. Basically, it's not "this works if you're using arch 8.0" but instead "this works if you have this package version."

I would say what is needed first of all is a framework: detail what needs to be done, set up a wiki, and encourage people to add information. A large part of the information could be moved from the current wiki.

The only difference from this and the current wiki is structure. And so it would need editors, and editorial decisions, to keep its proposed structure and consistency.

I'll definitely help. First of all we need volunteers.

Last edited by Weeks (2007-04-04 20:04:20)

cactus · 2007-04-04 21:54:05

No need to layer administrativa on top of something that is currently just an idea.
I say just start a section in the current wiki, and start "having at it".

emphire · 2007-04-04 22:32:56

I think one thing that would really help would be to add a section on adding to the documentation to the documentation and encourage them to do it. It shouldn't be buried somewhere you can't find it without searching for either. It should be clearly referenced as part of the install/getting started instructions.

I've never edited a wiki (I know they're pretty common). If there was a short section on how to do it then I think I'd be more likely to make the effort. Also for some reason, I always feel uneasy about editing a wiki without an invitation to do so.

emphire · 2007-04-04 22:36:08

Another thing... I think it would be helpful if there was more of a flow to the documentation (like there is to the freebsd handbook). Right now it just seems like a bunch of scattered articles with no flow.

It would be nice if every document was reachable by atleast one path from the main 'handbook' article.

skymt · 2007-04-05 00:07:03

Well, here it is. I've bootstrapped the page, drawing inspiration for the general outline from the FreeBSD handbook. It's currently content-free, and I don't have time tonight to add to it. Please work on it some if you have the time.

BTW: emphire, the wiki has a quick wiki-editing tutorial.

tlaloc · 2007-04-05 07:38:02

Thanks for that, skymt - a concrete plan is more important than volunteers.

However, the structure looks a bit like the (already existing) Beginner's guide. I think that this project should be different - more aimed at fine-tuning, experienced users, and Arch-specific things. A section on init scripts would be the first to come to my mind ...

Well, somehow I feel that the plan needs to be refined before actual work on it starts.

danboland · 2007-04-05 16:59:07

I agree about some sort of documentation on init scripts, i know the basics of them now, but thats only after a spen a descent amount of time shifting through them and figuring out what does what and what i needed to change.

As far as a doc for experience users though i think that would be a waste, since most experienced users wouldn't need a doc to let them know how to edit a linux system.

Maybe just some sort of detailed explanation about how arch is layed out on your computer and where all the importunes stuff are.

pelle.k · 2007-04-05 19:17:38

As far as a doc for experience users though i think that would be a waste, since most experienced users wouldn't need a doc to let them know how to edit a linux system.

Not the arch linux specifics, take the init system as an example. How, and what files are used. How to write your own init/daemon. Did you for example know that daemons get registered in /var/run daemons when succesfully started? And that rc.multi/functions is responsible for that (and how)? Or that rc.sysinit is resposible for setting you system locale?

Or how to use makepkg/makeworld in archlinux? Again, even if there already is a wiki entry about this, it should be a part of a compiled doc covering basic system maintenance in arch.

Some of the already present wiki articles (like setting up a network connection) though already existing, should be a part of this documentation. If necessary, expand them.

toofishes · 2007-04-05 20:40:40

I encourage all of you to get these ideas in concrete form in the wiki, even if they aren't perfect at first. Remember that anyone can edit (almost) anything there. Wikis are great for linking between articles, keep that in mind.

I like the idea of documenting how Arch initscripts work, that is something people would likely find interesting. It could also link to an article with a default rc.d file so people would know how to create their own, etc.

If it is good enough I'll be sure to link to it from the front page.

Arch Linux

#1 2007-04-04 16:12:13

complete arch (system) documentation?

#2 2007-04-04 16:40:35

Re: complete arch (system) documentation?

#3 2007-04-04 20:03:25

Re: complete arch (system) documentation?

#4 2007-04-04 21:54:05

Re: complete arch (system) documentation?

#5 2007-04-04 22:32:56

Re: complete arch (system) documentation?

#6 2007-04-04 22:36:08

Re: complete arch (system) documentation?

#7 2007-04-05 00:07:03

Re: complete arch (system) documentation?

#8 2007-04-05 07:38:02

Re: complete arch (system) documentation?

#9 2007-04-05 16:59:07

Re: complete arch (system) documentation?

#10 2007-04-05 19:17:38

Re: complete arch (system) documentation?

#11 2007-04-05 20:40:40

Re: complete arch (system) documentation?

Board footer