How to write a HOWTO: Difference between revisions
Prabuanand (talk | contribs) (moved Sample page layout from Help:Style) |
Prabuanand (talk | contribs) (cleaned up the page content and headings to make it easier to read and follow) |
||
| Line 1: | Line 1: | ||
If you are reading this, it probably means you are interested in contributing a | 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 these simple steps and you will end up with a great HOWTO in no time. | ||
== Prerequisite == | == Prerequisite == | ||
* | * "Use the formatting and other tools in [[Help:Editing]] page. Use [[Help:Cheatsheet|Cheatsheet]] for quick reference. | ||
* Follow [[Help:Style]] guidelines | * Follow [[Help:Style]] guidelines. | ||
== Steps for creating a HOWTO == | == Steps for creating a 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. | # 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. | ||
# | # 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. | ||
# Paste the [[#Sample_page_layout|Sample_page_layout]] into your new Temporary page. | # Paste the [[#Sample_page_layout|Sample_page_layout]] into your new Temporary page. | ||
# Follow the instructions in the template. | # Follow the instructions in the template. | ||
# 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 | # Finally, either 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 preserves the revision history from the original page. | ||
== | == Tips for an effective HOWTO == | ||
# Know your readers and what you are trying to tell them to do. | |||
# Write the summary. | |||
# Know your readers and what you are trying to tell them to do | |||
# Write the summary | |||
# Write the background info/prerequisites readers need. | # Write the background info/prerequisites readers need. | ||
# Answer the following three questions, at least in your head. | # Answer the following three questions, at least in your head. | ||
| Line 38: | Line 29: | ||
== Sample page layout == | == Sample page layout == | ||
A sample page with sections headings is given below as recommendation for all wiki pages including | A sample page with sections headings is given below as recommendation for all wiki pages including HOWTOs as per [[Help:Style]] guidelines: | ||
Introductory section containing a concise summary of the page so readers can decide quickly | Introductory section containing a concise summary of the page so readers can decide quickly | ||
| Line 45: | Line 36: | ||
== Prerequisite == | == Prerequisite == | ||
If there are any | If there are any prerequisites, they must be listed here. Readers might need to get ready before they can do the work, so explain those prerequisites first. | ||
== Installation == | == Installation == | ||
This section must contain information on [[:Template:pkg|packages]] needed to complete the task. | |||
== Configuration == | == Configuration == | ||
The Configuration section must follow with detailed sub-headings to handle all subtopics. Write the steps | The Configuration section must follow with detailed sub-headings to handle all subtopics. Write the steps on how to do something in this section. Show [[:Template:cat|file contents]] and [[:Template:Cmd|commands]] involved. Always include [[:Template:path|complete path]] in the steps. Break this procedure into separate sections to avoid more than 7-9 steps per section. | ||
== Troubleshooting == | == Troubleshooting == | ||
| Line 61: | Line 52: | ||
== See also == | == See also == | ||
Point your readers to related information they may refer | Point your readers to related information they may refer to, as not all information may not fit here. Add both internal wikilinks and external references relevant to this page in this section. | ||
Every page should be assigned at least one [[Help:Editing#categories|category]]. So add one of the relevant [[Special:Categories| | Every page should be assigned at least one [[Help:Editing#categories|category]]. So add one of the relevant [[Special:Categories|categories]] to your page. | ||
== See also == | == See also == | ||
Latest revision as of 18:41, 13 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 these simple steps and you will end up with a great HOWTO in no time.
Prerequisite
- "Use the formatting and other tools in Help:Editing page. Use Cheatsheet for quick reference.
- Follow Help:Style guidelines.
Steps for creating a 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.
- 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 Sample_page_layout into your new Temporary page.
- Follow the instructions in the template.
- Finally, either 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 preserves the revision history from the original page.
Tips for an effective HOWTO
- Know your readers and what you are trying to tell them to do.
- 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 the steps to do it.
- Clean up your work.
- Revise, revise, revise.
Sample page layout
A sample page with sections headings is given below as recommendation for all wiki pages including HOWTOs as per Help:Style guidelines:
Introductory section containing a concise summary of the page so readers can decide quickly whether to read it. This section appears right below the page title. == Prerequisite == If there are any prerequisites, they must be listed here. Readers might need to get ready before they can do the work, so explain those prerequisites first. == Installation == This section must contain information on packages needed to complete the task. == Configuration == The Configuration section must follow with detailed sub-headings to handle all subtopics. Write the steps on how to do something in this section. Show file contents and commands involved. Always include complete path in the steps. Break this procedure into separate sections to avoid more than 7-9 steps per section. == Troubleshooting == Troubleshooting section must include common errors that may be encountered by the users. == See also == Point your readers to related information they may refer to, as not all information may not fit here. Add both internal wikilinks and external references relevant to this page in this section. Every page should be assigned at least one category. So add one of the relevant categories to your page.