How to write a HOWTO: Difference between revisions

Revision as of 18:36, 12 December 2025

If you are reading this, it probably means you are interested in contributing a Howto or Tutorial to Alpine Linux Wiki. This is great! Just follow those simple steps and you will end up with a great howto in no time.

Prerequisite

Refer to Help:Editing to understand the Text Formatting Rules. Lookup Cheatsheet for quick reference.
Follow Help:Style guidelines at all times.
Learn to format Wiki text.
- By clicking the Edit page button on Alpine Linux Wiki articles to read the source. Do not accidentally modify them.
- By experimenting in Sandbox.

Writing the HOWTO

Login to Alpine Linux Wiki. If you have never logged in, click the Log in / create account on the top-right, and then click the Create an account link.
Pay proper attention to name your page. Changing the name of pages in Wiki is not trivial. If you are new to Wiki editing, use a subpage of your User namespace like Username/Learning to Use Wiki or use Sandbox to create a Temporary page first.
Paste the [Help:Style#Sample_page_layout|Sample_page_layout]] into your new Temporary page.
Follow the instructions in the template.
Pay attention while creating Heading/subheading, as they can be linked within the page and from other wiki pages.
Try as much as possible to refer existing wiki content for standard tasks like installation, partitioning, formatting, user management, managing repositories etc.. instead of repeating the same in your page. This avoids confusing users and prevents content fragmentation.
Always update existing wiki pages so that information with existing wiki links also gets benefited. New pages must be created sparingly, i.e only if it is absoultely needed.
Finally move your temporary page or create a properly named HOWTO page as explained in Help:Editing and paste your content from the temporary page. Moving a page captures the change log from the original page.

Quick guidelines for a Howto

Know your readers and what you are trying to tell them to do and
Write the summary
Write the background info/prerequisites readers need.
Answer the following three questions, at least in your head.
1. What do I explain how to do?
2. How do I do that?
3. What do HOWTO readers already know about doing that?
Write up the steps to do it.
Clean up your work.
Revise, revise, revise.

@@ Line 11: / Line 11: @@
 == Writing the HOWTO ==
-Know your readers and what you are trying to tell them to do and pay proper attention to name your page. Changing the name of pages in Wiki is not trivial.
+# Login to Alpine Linux Wiki. If you have never logged in, click the Log in / create account on the top-right, and then click the Create an account link.
-#Login to Alpine Linux Wiki.{{tip|If you have never logged in, click the Log in / create account on the top-right, and then click the Create an account link.}}
+# Pay proper attention to name your page. Changing the name of pages in Wiki is not trivial. If you are new to Wiki editing, use a subpage of your User namespace like [[Special:MyPage/Learning to Use Wiki|Username/Learning to Use Wiki]] or use [[Sandbox]] to create a Temporary page first.
-#Read the basics of wiki editing with specific reference to Alpine Wiki at [[Help:Editing]] and [[Help:Cheatsheet]].
+# Paste the [Help:Style#Sample_page_layout|Sample_page_layout]] into your new Temporary page.
-#If you are new to Wiki editing, use a subpage of your User namespace like [[Special:MyPage/Learning to Use Wiki|Username/Learning to Use Wiki]]  or use [[Sandbox]] to create a Temporary page first.
+# Follow the instructions in the template.
-#Paste the [[#Basic_HOWTO_Template|Basic HOWTO Template]] into your new Temporary page.
+# Pay attention while creating Heading/subheading, as they can be linked within the page and from other wiki pages.
-#Follow the instructions in the template.
+# Try as much as possible to refer existing wiki content for standard tasks like [[installation]], [[Setting_up_disks_manually#Manual partitioning|partitioning]], [[Setting_up_disks_manually#Formatting_partitions|formatting]], [[Setting_up_a_new_user#Creating_a_new_user|user management]], [[Repositories#Managing_repositories|managing repositories]] etc.. instead of repeating the same in your page. This avoids confusing users and prevents content fragmentation.
-#Pay attention while creating Heading/subheading, as they can be linked within the page and from other wiki pages.
+# Always update existing wiki pages so that information with existing wiki links also gets benefited. New pages must be created sparingly, i.e only if it is absoultely needed.
-#Try as much as possible to refer existing wiki content for standard tasks like [[installation]], [[Setting_up_disks_manually#Manual partitioning|partitioning]], [[Setting_up_disks_manually#Formatting_partitions|formatting]], [[Setting_up_a_new_user#Creating_a_new_user|user management]], [[Repositories#Managing_repositories|managing repositories]] etc.. instead of repeating the same in your page. This avoids confusing users and prevents content fragmentation.
+# Finally move your temporary page or create a properly named HOWTO page as explained in [[Help:Editing]] and paste your content from the temporary page. Moving a page captures the change log from the original page.
-#Always update existing wiki pages so that information with existing wiki links also gets benefited. New pages must be created sparingly, i.e only if it is absoultely needed.
-#Finally move your temporary page or create a properly named HOWTO page as explained in [[Help:Editing]] and paste your content from the temporary page. Moving a page captures the change log from the original page.
-== Basic HOWTO Template ==
+=== Quick guidelines for a Howto ===
-A WikiText skeleton of a basic HOWTO based on [[Help:Style#Sample page layout|Sample page layout]]:
+# Know your readers and what you are trying to tell them to do and
+# Write the summary
- Summarize your article in the Introduction section so readers
+# Write the background info/prerequisites readers need.
- can decide quickly whether to read it. This section appears
+# Answer the following three questions, at least in your head.
- right below the page title.
+## What do I explain how to do?
+## How do I do that?
- == Prerequisite ==
+## What do HOWTO readers already know about doing that?
+# Write up the steps to do it.
- Your readers might need to get ready before they can do the work.
+# Clean up your work.
- If so explain those prerequisites first.
+# Revise, revise, revise.
- == Installation ==
- This section might alternatively contain background information
- readers need to do to carry out your instructions.
- == Configuration ==
- Write the steps of how to do something in this section. If
- possible, show an example first, then tell your readers the steps.
- Break this procedure into separate sections to avoid more than
- about 7-9 steps per section. Shown below is sample steps.
- # Write the summary
- # Write the background info/prerequisites readers need.
- # Answer the following three questions, at least in your head.
- ## What do I explain how to do?
- ## How do I do that?
- ## What do HOWTO readers already know about doing that?
- # Write up a good example. This ensures you can do it.
- # Write up the steps to do it.
- # Clean up your work.
- # Revise, revise, revise.
- == See also ==
- Point your readers to related information they may refer
- further, as every information does not fit in your HOWTO.
- Remember to add  both internal wiki links and external
- references.
- Every page should be assigned at least one [[Help:Editing#categories|category]].
- So add one of the relevant [[Special:Categories|category]] to your page.
 == See also ==
@@ Line 73: / Line 38: @@
 *[[Help:Cheatsheet|Cheatsheet for Alpine Linux Wiki]]
 *[[Project:Wiki etiquette|Wiki etiquette]]
 [[Category:Wiki]]