This page provide some guidelines on how to add/edit/contribute to the DebianOn effort.
DebianOn is an effort to document how to install, configure and use Debian on some specific hardware. Therefore potential buyers would know if that hardware is supported and owner would know how get the best out of that hardware.
The purpose is not to duplicate the Debian Official Documentation, but to document how to install Debian on some specific hardware.
Coding Style... Ok, it isn't about coding, but it is about style...
Re-use existing page fragment. MoinMoin wiki let you include a page in another page. So for instance, if the Dell Latitude D620 uses the same wireless card as the Thinkpad T60, you could put that section in a page named InstallingDebianOn/PageFragmentIntelIpw3945/etch, then include it from both the T60 and the D620 using: <<Include(InstallingDebianOn/PageFragmentIntelIpw3945/etch)>>
Note that PageFragmentIntelIpw3945/etch is directly under "InstallingDebianOn", because both configuration steps are identical for both laptops.
If later it happen that the Dell Latitude have some specific configuration steps, one should copy InstallingDebianOn/PageFragmentIntelIpw3945/etch to InstallingDebianOn/Dell/Latitude/PageFragmentIntelIpw3945/etch.
Don't over-use links
- Pages overloaded with links are less readable (Ideally, the reader just have to follow the recipe from top to bottom).
- Many links can be moved to the resources section.
- Do give credits to authors (in the credits section !). Preferably with name, URL and purpose.
Use ! in front of !CamelCaseWords to avoid automatic linking.
Don't overload page / keep it short.
- If the explanation of a specific point gets too long, just link to a dedicated page.
moinmoin wiki allows to automatically create Footnotes, see 1
Follow the direction: when you edit some InstallingDebianOn* pages, there are lots of indications in the page comments (lines beginning with ##)
Subscribe : You are encouraged to subscribe to the InstallingDebianOn page(s) for the configuration you have (For instance, subscribe to !InstallingDebian/Dell/!?LatitudeD620.*). The ".*" is meant to catch "/Discussion" pages. (?UserPreferences).
You might be pleased to be notified for solved problem.
HowTo Add/Edit a Specific Computer Model
This section give advice to add or edit a computer model (like Thinkpad T61)
Quick : It's better to fill a quick, incomplete report (and still accurate), than no report at all.
Name of the page : In order to be consistent, the page should be name something like !InstallingDebianOn/Mycomputerbrand/Mycomputermodel. So it is clearly affiliated to !InstallingDebianOn/Mycomputerbrand.
Template : If a template named like "!InstallingDebianOn/!MycomputerbrandTemplate" exists, you should use it. Otherwise, use "!InstallingDebianOn/!?GenericComputerTemplate" or "!InstallingDebianOn/!?GenericLaptopTemplate" or "!InstallingDebianOn/!?GenericServerTemplate"
Fresh install (?) : It is best to write installation guide while actually installing Debian from scratch. otherwise, write in your report that it isn't a clean install.
Device Status : Accuracy IS important. If you haven't tested a feature, simply write it ! (Not Tested). If you couldn't get a feature to work, write it ! (Work Needed). If your confident there's no driver, write it (No driver in Etch, or Not yes supported by upstream driver as of 2006/12/31 (see http://somewhere/)), etc..
Installation and Bug Reports : Open bugs and make an installation-report when needed. It isn't a duplicate work : bug report (including installation-report) are useful to to developers to prepare the next version/release of Debian. Whereas a "DebianOn Installation Howto's" helps end-users of current Debian version. (You can still cross-link the bug and wiki pages).
Advertise the new howto : This is especially useful if this computer is part of a new product line, and the Installation Howto is quite complete.
Howto Add/Edit a Page Fragment
Work in progress
- Use Template
Name it like: ?PageFragmentDevicename(distribution) like PageFragmentIntelIpw3945/etch
- Try to guess how often that page fragment:
- Is it specific to a computer brand ? or usable for many computer brands ? (this will determine the parent page).
- If it is very generic, maybe it should just a regular page (with a very tiny page fragment... For instance, how to use ndiswrapper)
HowTo Add/Edit a Brand or Device Type
This section covers steps to add a new computer brand (like Toshiba) or a new generic kind of devices (Watch running Linux, may be).
PageName : Think twice of the name of your hub : InstallingDebianOn/Dell, ?InstallingDebianOn/DellLatitude, InstallingDebianOn/DellLaptop/, InstallingDebianOn/DellLaptop/Latitude+InstallingDebianOn/DellLaptop/Inspiron etc.. (I would choose InstallingDebianOn/IBM/Thinkpad because it's the only names for their laptop, but I would choose InstallingDebianOn/Asus/Laptop because there are many laptop models).
Template : Create the page based on template InstallingDebianOn/Laptop_template
Page Alias : It might be a good idea to create a dummy wiki page named just "Mycomputerbrand" and link it to InstallingDebianOn/Mycomputerbrand, therefore : 1.user searching for that brand would find it easily. 2. Nobody will create a clone page by mistake. That dummy page should just contain : #REDIRECT InstallingDebianOn/Mycomputerbrand
Who can contribute under InstallingDebianOn : Anybody, that's the purpose of a wiki !
What to contribute under InstallingDebianOn : Any return of experience in installing Debian on specific hardware. Again, InstallingDebianOn is not about how to use Debian Installer, neither is it a how to use some piece of software (but you are encourage contribute and link to such page).
Where to contribute : All ?InstallingDebian_On page are store on the Debian Wiki http://wiki.debian.org/InstallingDebian_On*.
When : Now or tomorrow (yesterday is just fine too). but 4 lines now are better than 2 pages never.
How : If the explanation in this page aren't clear enough, Just AskTM in InstallingDebianOn/Discussion.
Footnotes are used like this (1)