How to write a HOWTO: Difference between revisions

From Alpine Linux
m (remove bold from how to template)
(Added clarification on moving page, fixed typo, grammar)
 
(One intermediate revision by the same user not shown)
Line 4: Line 4:
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.
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.{{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.}}
#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.}}
#Read the basics of wiki editing with specific reference to Alpine Wiki at [[Help:Editing]].  
#Read the basics of wiki editing with specific reference to Alpine Wiki at [[Help:Editing]] and [[Help:Cheatsheet]].  
# If you are new to Wiki editing, use a subpage of your User namespace or use [[Sandbox]] to create a Temporary page first.
#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 [[#Basic_HOWTO_Template|Basic HOWTO Template]] into your new Temporary page.
#Paste the [[#Basic_HOWTO_Template|Basic HOWTO Template]] into your new Temporary page.
#Follow the instructions in the template.
#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]], [[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.  
#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 create the properly named HOWTO page as explained in [[Help:Editing]] and paste your content from the temporary 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.


== Learn to format Wiki text ==
== Learn to format Wiki text ==
*Refer [[Help:Editing]] to understand the Text Formatting Rules  
*Refer [[Help:Editing]] to understand the Text Formatting Rules.
*By clicking the Edit page button on Alpine Linux Wiki articles to read the source. Do not accidentally modify them.
*By clicking the Edit page button on Alpine Linux Wiki articles to read the source. Do not accidentally modify them.
*By experimenting in [[Sandbox]]
*By experimenting in [[Sandbox]]
*While editing wiki pages, you can lookup [[Help:Cheatsheet|Cheatsheet]] for quick reference.


== Basic HOWTO Template ==
== Basic HOWTO Template ==


A WikiText skeleton of a basic HOWTO:
A WikiText skeleton of a basic HOWTO:
== How To Do Something ==
  Summarize your article here so readers can decide
  Summarize your article here so readers can decide
  quickly whether to read it.
  quickly whether to read it. This line appears right
below the page Title.
   
   
  == Before You Start Title ==
  == Before You Start Title ==
Line 47: Line 49:
  #Write the summary.
  #Write the summary.
  #Clean up your work.
  #Clean up your work.
# Add relevant [[Special:Categories|category]] to your page, as every page should be assigned at least one Category.
  #Revise, revise, revise.
  #Revise, revise, revise.
   
   
  == See Also ==
  == See Also ==
  If you ought to point your readers to related information
  Point your readers to related information they may refer
  they no doubt need but that does not fit in your HOWTO, add links here.
  further, as every information does not fit in your HOWTO.
Remember to add both internal wiki links and external
references.
Every page should be [[Help:Editing#categories|assigned at least one category]].
So add relevant [[Special:Categories|category]] to your page.  


== See Also ==
== See Also ==
*[[Help:Editing]]
*[[Help:Editing]]
*[[Help:Cheatsheet|Cheatsheet for Alpine Linux Wiki]]
*[[Project:Wiki etiquette|Wiki etiquette]]
*[[Project:Wiki etiquette|Wiki etiquette]]
[[Category:Wiki]]
[[Category:Wiki]]

Latest revision as of 10:33, 12 December 2024

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.

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.

  1. 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.
  2. Read the basics of wiki editing with specific reference to Alpine Wiki at Help:Editing and Help:Cheatsheet.
  3. 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.
  4. Paste the Basic HOWTO Template into your new Temporary page.
  5. Follow the instructions in the template.
  6. Pay attention while creating Heading/subheading, as they can be linked within the page and from other wiki pages.
  7. 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.
  8. 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.
  9. 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.

Learn to format Wiki text

  • Refer Help:Editing to understand the Text Formatting Rules.
  • By clicking the Edit page button on Alpine Linux Wiki articles to read the source. Do not accidentally modify them.
  • By experimenting in Sandbox.
  • While editing wiki pages, you can lookup Cheatsheet for quick reference.

Basic HOWTO Template

A WikiText skeleton of a basic HOWTO:

Summarize your article here so readers can decide
quickly whether to read it. This line appears right 
below the page Title.

== Before You Start Title ==
Your readers might need to get ready before they can do the work.
If so explain those prerequisites first. This section might alternatively 
contain background information readers need to know before they can make 
sense of your example or carry out your instructions.

== Doing Something Title ==
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 procedures to avoid more than
about 7-9 steps per procedure.

 INSERT GREAT EXAMPLE HERE

#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.
#Write the background info/prerequisites readers need.
#Write the summary.
#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 category.
So add relevant category to your page. 

See Also