Help:Writing HOWTO

From openSUSE

Note: Ideas about layout and content of HOWTOs are very welcome.

General

By definition HOWTO is a step-by-step guide how to to solve one specific problem without too much theory. You can add section References and list there books and online information sources that you have used. That will help the readers with interest for more background information to find it, but article itself must be sufficient to solve practical problem.

The references must be accurate and easy to find. Dead links and books that no one can buy anymore are of no use.

Please don't duplicate effort. There is large collection of HOWTO articles on

• http://tldp.org

You can install collection of HOWTOs from CD/DVD or Internet openSUSE repositories using YaST. To locate it start YaST Software Management and type as search word howto. After installation you can find it in:

/usr/share/doc/howto 

Also check the openSUSE list of HOWTOs. There is already quite large collection of articles, if one already exist that covers the subject that you wish to write about than take time to read it and see if it can be improved.

If you are writing this kind of article for the first time they can be good guide how to do that.

Sections

• Introduction - what kind problem is solved using this HOWTO. Be specific and list operating system version(s) and hardware that procedure is applied to, what is used to test the procedure. You can use categories if you are sure that article applies to whole groups of devices or software.
• Acknowledgments - people that helped in any form your writing deserve to be mentioned. Open source software is mostly free, but that doesn't mean that contributors should be anonymous. Your wiki user name will be registered in article history, and it is not necessary to be mentioned explicitly, but external authors must be mentioned in HOWTO article.
• Prerequisites - in software, hardware and knowledge.
• Procedure
• Conclusions - digest of procedure (may be skipped if procedure itself is very short)
• References - books, online

Layout

This is page formating, placement of index, tables and images.

See also

• OpenSUSE Style Guide

External links

• http://tldp.org/docs.html#howto is the home of HOWTOs
• LDP templates is list that includes template for HOWTOs. It is zip archive. In KDE use Ark to open.