Bryan Østergaard (![[info]](http://l-stat.livejournal.com/img/userinfo.gif){kind=small} kloeri) wrote,@ 2009-03-05 20:20:00 |
|
Contributing to Exherbo documentation
In one of my recent blog posts a user commented that it would be great if we added our documentation to a git repository as that would make it much easier to contribute. In fact all of our website has always been in git but it hasn't always been public and we haven't been very good at describing the setup so I'll try to describe our current setup now.
Our setup
Our website is spread over two different repositories.
The first repository is called www.git and contains what be considered the "main" website - that is our frontpage, the list of developers and links to various resources and the available documentation. The www repository isn't particularly interesting and doesn't get a lot of updates.
The second repository is docs.git which all the real documentation available through the website such as Exheres-for-smarties, our FAQ and installation guide. This repository gets frequent commits as we update Exheres-for-smarties to reflect changes in the exheres-0 EAPI and correct or clarify existing documentation. This is the repository most patches should be made against.
You can browse through both repositories using gitweb or clone the repositories using git clone git://git.exherbo.org/docs.git and git clone git://git.exherbo.org/www.git. Looking through the contents you should notice two things:
1. We use Markdown for all our documentation. Markdown is a very easy format to describe paragraphs, headers, lists and so on in a format very close to normal text files.
2. HTML generation is driven by Makefiles. These makefiles are run from a git hook and automatically generates the HTML code used on our website every time one of us pushes new content to the repositories. We only have one webserver at the moment so there's no syncing between nodes or any other complexities involved in this process.
The Makefiles is also worth looking at if you don't have much experience with make as they use a couple tricks to generate the needed rules based on wildcards.
Contributing documentation
If you want to help fix current documentation (typos, badly worded text and so on) you should follow the same instructions as if you were contributing a package. There's a few differences of course as you can ignore all the exheres specific stuff but the git configuration should follow that guide and we're going to want a git format-patch that we can apply directly to our repositories.
For larger contributions you'll likely want to talk to me first (kloeri on irc.freenode.net or kloeri@exherbo.org) to make sure that we want to add your document(s) to the website and that we agree on the contents of it before spending a lot of time on writing. We're quite open to contributions but we also have fairly specific ideas on the direction we want for Exherbo now and the near future so it's important that we coordinate larger updates to the documentation and/or website.
That said, we could use an update for Contributing to cover documentation as well - please let me know if you're interested in helping with this and I'll try to coordinate it.
Update:
I've just fixed the www.git Makefile to use maruku like docs.git always have. So you should check formatting using the dev-ruby/maruku package.
In one of my recent blog posts a user commented that it would be great if we added our documentation to a git repository as that would make it much easier to contribute. In fact all of our website has always been in git but it hasn't always been public and we haven't been very good at describing the setup so I'll try to describe our current setup now.
Our setup
Our website is spread over two different repositories.
The first repository is called www.git and contains what be considered the "main" website - that is our frontpage, the list of developers and links to various resources and the available documentation. The www repository isn't particularly interesting and doesn't get a lot of updates.
The second repository is docs.git which all the real documentation available through the website such as Exheres-for-smarties, our FAQ and installation guide. This repository gets frequent commits as we update Exheres-for-smarties to reflect changes in the exheres-0 EAPI and correct or clarify existing documentation. This is the repository most patches should be made against.
You can browse through both repositories using gitweb or clone the repositories using git clone git://git.exherbo.org/docs.git and git clone git://git.exherbo.org/www.git. Looking through the contents you should notice two things:
1. We use Markdown for all our documentation. Markdown is a very easy format to describe paragraphs, headers, lists and so on in a format very close to normal text files.
2. HTML generation is driven by Makefiles. These makefiles are run from a git hook and automatically generates the HTML code used on our website every time one of us pushes new content to the repositories. We only have one webserver at the moment so there's no syncing between nodes or any other complexities involved in this process.
The Makefiles is also worth looking at if you don't have much experience with make as they use a couple tricks to generate the needed rules based on wildcards.
Contributing documentation
If you want to help fix current documentation (typos, badly worded text and so on) you should follow the same instructions as if you were contributing a package. There's a few differences of course as you can ignore all the exheres specific stuff but the git configuration should follow that guide and we're going to want a git format-patch that we can apply directly to our repositories.
For larger contributions you'll likely want to talk to me first (kloeri on irc.freenode.net or kloeri@exherbo.org) to make sure that we want to add your document(s) to the website and that we agree on the contents of it before spending a lot of time on writing. We're quite open to contributions but we also have fairly specific ideas on the direction we want for Exherbo now and the near future so it's important that we coordinate larger updates to the documentation and/or website.
That said, we could use an update for Contributing to cover documentation as well - please let me know if you're interested in helping with this and I'll try to coordinate it.
Update:
I've just fixed the www.git Makefile to use maruku like docs.git always have. So you should check formatting using the dev-ruby/maruku package.
