Difference between revisions of "Write a "How Do I..." Article"

From Gramps
Jump to: navigation, search
m (Embed your user tag)
m (replace {{version manual}} template with {{man version}})
 
(20 intermediate revisions by the same user not shown)
Line 2: Line 2:
 
;How do I write a "How Do I..." Article
 
;How do I write a "How Do I..." Article
  
The "[[:Category:How do I...|How Do I...]]" series of articles are designed to provide new users with some basic, step-by-step instructions on how to perform a specific task in Gramps. Articles should be targeted to users who are not familiar with Gramps, and may not be familiar to computing in general.
+
The "[[:Category:How do I...|How Do I...]]" series of articles are designed to provide new users with some basic, step-by-step instructions on how to perform a specific task in Gramps. It is not a tutorial about fully exploring a feature. These articles are about how to achieve a specific task without digressing into interesting distractions.
  
{{man note|''How do I...'' articles don't have to be pretty or professionally wtitten.|''They just need to make correct & useful information more accessible.'' <br /><br />Please be aware every public page may be edited by anyone. Each WikiContributor has pet projects to improve quality of pages... hotlinking, consistency of terminology, grammar, punctuation, order of presentation... all are likely to be changed. <br /><br />'''Don't take offense because none is intended'''. When someone edits your page, they are saying that they found value in what you wrote. Enough that it worth their time to pitch in. They might ''accidentally'' mess it up. If that happens, revert the content using the [https://meta.wikimedia.org/wiki/Special:MyLanguage/Help:Page_history History] and clarify what they misinterpreted.}}
+
Articles should be targeted at users who are not familiar with a particular task or workflow... yet written with the assumption that they are familiar with basic Gramps terms and core concepts. After the article covers the task, hotlinking Gramps terms and concepts when first used in the article extends the usefulness of the article for users who are not familiar with Gramps, and may not be familiar to computing in general.  
  
==Build an fresh article==
+
{{man tip|To much repetition of introductory material is bad|Even when a workflow uses something esoteric like Attributes, [[Gramps_Glossary#attribute|a link to <u>'''Attribute'''</u> in the Glossary]] saves digressing into what Attributes are and how to create Custom Types ... all you have to say is what Attribute custom type definition should be used. It simplifies the workflow into concepts that are easier to understand rather than endless intricate steps. Also, it saves rework. <br /><br />Each time the Glossary or Introductory section is improved, every article that uses those links is also improved. Linked sections ensure that the feature is described consistently and comprehensively.}}
Creating a wiki page can be intimidating. But you do '''''not''''' have to start from scratch.
+
 
 +
Rather than explain each step in excruciating detail, it is recommended that you link unique Gramps processes to the [[Gramps_Glossary|Glossary]] term ''(preferred)'' or [[Gramps_{{man version}}_Wiki_Manual|introductory section]] of the manual. You can link Genealogical terms to the [[Genealogy_Glossary|Genealogy Glossary]]. Linking to Glossaries is preferred because it tersely describes the term or concept and should link to more introductory section.
 +
 
 +
{{man note|''How do I...'' articles don't have to be pretty or professionally written.|''They just need to make correct & useful information more accessible.'' <br /><br />Please be aware every public page may be edited by anyone. Each WikiContributor has pet projects to improve quality of pages... hotlinking, consistency of terminology, grammar, punctuation, order of presentation... all are likely to be changed.<br /><br />But premature edits can step on an outline being expanded. Include a Warn note at the top if you need a few days without being interrupted by edits to complete your creative process.<br /><br />'''Don't take offense because none is intended'''. When someone edits your page, they are saying that they found value in what you wrote. Enough that it is worth their time to pitch in. They might ''accidentally'' mess it up. If that happens, revert the content using the [https://meta.wikimedia.org/wiki/Special:MyLanguage/Help:Page_history History] and clarify what they misinterpreted.}}
 +
 
 +
==Build a fresh article==
 +
Creating a wiki page can be intimidating. But you do '''''not''''' have to start from scratch. Gramps has [[#Add "How Do I..." standard form|template/outline]] that can be filled in and which has examples of much of the unique formatting. (You cut&paste from the outline's example section and discard that whole section when the page is ready for the public.)
  
 
===Create a page===
 
===Create a page===
The conventional suggestion for creating an expansion page on the wiki is to edit a page where the concept is only mentioned in passing and adding a 'link' to a term on the page. This is a good method if you've built the page offline and just want to paste in the [https://mediawiki.org/wiki/Help:Formatting MediaWiki markup language] code. But when using the MediaWiki editor to slowly build a page from scratch, it adds a dead link in a highly visible way.
+
The MediaWiki tool has [https://www.mediawiki.org/wiki/Help:Starting_a_new_page several methods start a new page] when you want to add content. A good method is editing your 'user page' to insert a 'broken' [https://www.mediawiki.org/wiki/Help:Links#Internal_links internal link].  
 +
{{man tip|If a core concept is missing from the Glossary...|Rather than writing foundation information into your article, consider adding a new term with the terse description to the  [[Gramps_Glossary|Gramps Glossary]] or general [[Genealogy_Glossary|Genealogy Glossary]].  Then link your new article to the new Glossary term. Include a link under the Glossary term to the introductory material, preferably in the Gramps wiki. <br /><br />Writing in a glossary page is about the same amount of work as in an article page ... and you won't have to recreate the work for another article.}}
  
You can create a Work-In-Progress page with a particular name by using the [https://mediawiki.org/wiki/Help:Searching Search box] in the left side bar. (The name is important because it determines how the content will be listed in the Category indices.) The search will try to list articles with all the terms entered. But if there isn't a phrase match for the title, the first option will also offer a red link at the top that would create a page.
+
Clicking that red, broken link will display a message that no page with that name exists and offers to create a blank page.  
  
===Add "How Do I.." standard form===
+
The conventional recommendation for creating an expansion pagespace on the wiki is to create a link from another page...  where the concept is only mentioned without enough explanation. Just [[:Help:Editing_pages|edit the page]] and add a 'link' to the under-explained concept (or term) on that page.  
Take advantage of the [[:Category:Templates|template]] for [[Template:How_do_I|How do I...]] to create a framework for the article. Use MediaWiki's [https://www.mediawiki.org/wiki/Transclusion subclusion] (''substitution [https://www.mediawiki.org/wiki/Transclusion transcribed inclusion]'')  feature by pasting the following line in the new document and saving it. The '''subst:''' before the template name will cause the content to be substituted into the editable workspace as the page is saved.  
 
  
===Embed your user tag===
+
Simply insert a line like:
The row of 4 tilde (&tilde;&tilde;&tilde;&tilde;) characters will add a datestamp line at the bottom with your hyperlinked WikiContributor name.
+
&#91;&#91;wiki page name|my page name hotlinked label]]
 +
 
 +
While this creates a dead link, clicking on it will spawn a new pagespace where you can add the extra information. This new pagespace will show up in the indexing and Categories exactly as in the portion before the vertical bar ("&vert;"). So consider capitalization and wording. (Take a look at other pages listed in the [[:Category:How_do_I...|How do I...]] category for a point of reference.)
 +
 
 +
This is a good method if you've built the page content offline and just want to paste in the [https://mediawiki.org/wiki/Help:Formatting MediaWiki markup language] code. But when using the MediaWiki editor to slowly build a page from scratch, this approach adds a dead link in a highly conspicuous way. Once the first edit is saved, the link will be 'live' but might be a crude draft.
  
<Code>[[User:Bamaustin|Bamaustin]] ([[User talk:Bamaustin|talk]]) {{LOCALTIME}}, {{LOCALDAY}} {{LOCALMONTHNAMEGEN}} {{LOCALYEAR}} (UTC)</Code>
+
Alternately, when starting a new pages, you can create the originating link on your [[:Category:WikiContributors|WikiContributor]] '''user page''' or '''discussion''' pages instead of from an existing page. You'll be able to find it easily while it is still a '''Work-In-Progress'''. It can be a helpful reminder to also include a link to the target page where you intend to cross-reference the finalized new content.
  
This adds the incomplete page to the page list generated when you click "[[Special:WhatLinksHere/Write_a_%22How_Do_I...%22_Article|What links here]]" in the left sidebar on your WikiContributor page.  
+
As a last resort, you can create a Work-In-Progress pagespace with a particular name by using the [https://mediawiki.org/wiki/Help:Searching Search box] in the left side bar. (Again, the name is important because it determines how the content will be listed in the Category indices.) The search will try to list articles with all the terms entered. But if there isn't a phrase match for the title, the first option will also offer a red link at the top that would create a page.
  What links here:
 
  Page: [[{{PAGENAME}}|{{PAGENAME}}]] Article
 
  
You can use this to make a work-in-progress (WIP) page list. When the page is complete enough to be made public & linked, remove the line to remove it from your WIP page list. (The '''Contributions''' link will still help you find the page but there would be more clutter.)
+
===Add "How Do I..." standard form===
 +
Take advantage of the [[:Category:Templates|template]] called "[[Template:How_do_I|Template:How do I]]" to insert a outline framework (with examples) for the article. That framework can be built by pasting the following lines in the newly created pagespace and saving it.  
 
<pre>
 
<pre>
 
{{subst:Template:How_do_I}}
 
{{subst:Template:How_do_I}}
Line 32: Line 41:
 
~~~~
 
~~~~
 
</pre>
 
</pre>
 +
What do these lines do?
 +
====Use the template====
 +
The double curley brackets (<code>{{</code> <code>}}</code>) identify a named template. This uses MediaWiki's [https://www.mediawiki.org/wiki/Transclusion transclusion] (''[https://www.mediawiki.org/wiki/Transclusion transcribed inclusion]'') feature for the [[Template:How_do_I|How do I...]] template to re-use the content stored in that pagename. It is similar to [https://wikipedia.org/wiki/Server_Side_Includes Server Side Includes]. Think of it as a smarter version of cut&paste.
 +
 +
The '''<code>subst:Template:</code>''' before the template name uses the subclusion (''[https://mediawiki.org/wiki/Help:Substitution substitution] [https://www.mediawiki.org/wiki/Transclusion transcribed inclusion]'') feature for templates. This will cause the template content to be processed &amp; substituted into the editable workspace as the page is saved. Because this content can now be refined without changing other pages, it is more "recycled" than "re-used".
 +
 +
====Embed your user tag====
 +
The row of 4 tilde (&tilde;&tilde;&tilde;&tilde;) characters will add a datestamp line at the bottom with your hyperlinked WikiContributor name. 
 +
 +
<code>[[User:Not_a_valid_user|Not a valid user]] ([[User talk:Not_a_valid_user|talk]]) {{LOCALTIME}}, {{LOCALDAY}} {{LOCALMONTHNAMEGEN}} {{LOCALYEAR}} (UTC)</code>
 +
 +
This adds the incomplete page to the page list generated when you click "[[:Special:WhatLinksHere/User:Not_a_valid_user|What links here]]" in the left sidebar on your WikiContributor page similar to the following:
 +
  What links here:
 +
  Page: [[{{PAGENAME}}|{{PAGENAME}}]] Article
 +
 +
You can use this to make a work-in-progress (WIP) page list. When the page is complete enough to be made public & linked, remove the line to remove it from your WIP page list. (The '''Contributions''' link will still help you find the page but there would be more clutter.)
  
 
== Possible Topics ==
 
== Possible Topics ==
 
&#x1F6A7;
 
&#x1F6A7;
 
* [[How to find the relationship between people|How do I find the relationship between people?]] ✔  
 
* [[How to find the relationship between people|How do I find the relationship between people?]] ✔  
* How do I specify an adopted child or a step child?  
+
* How do I specify an [[Events_in_Gramps#Adopted|adopted]] child or a [[Step_relationships|step]] child?  
* How do I prevent private data from being displayed in reports?
+
* How do I prevent [[Gramps_Glossary#private_tag|private data]] from being displayed in reports?
* How do I apply a filter to a display?
+
* How do I apply a [[Gramps_{{man version}}_Wiki_Manual_-_Filters|filter]] to a display?
* How do I handle multiple names for a single person?
+
* How do I handle [[Gramps_{{man version}}_Wiki_Manual_-_Entering_and_editing_data:_detailed_-_part_1#Multiple_Surnames|multiple names]] for a single person?
* How do I get help?
+
* How do I get [[Contact#Mailing_lists|help]]?
 
* [[How_to_create_a_good_bug_report|How do I report a bug?]]  ✔  
 
* [[How_to_create_a_good_bug_report|How do I report a bug?]]  ✔  
* How do I request a feature
+
* How do I [[Contact#Requesting_enhancements|request a feature]]
* How do I create a Familytree chart?
+
* How do I create a Familytree or a [[:Howto:_Make_a_relationship_chart|Relationship]] chart?
  
 
[[Category:How do I...]]
 
[[Category:How do I...]]
 +
[[Category:WikiContributors]]

Latest revision as of 18:47, 6 July 2021

How do I write a "How Do I..." Article

The "How Do I..." series of articles are designed to provide new users with some basic, step-by-step instructions on how to perform a specific task in Gramps. It is not a tutorial about fully exploring a feature. These articles are about how to achieve a specific task without digressing into interesting distractions.

Articles should be targeted at users who are not familiar with a particular task or workflow... yet written with the assumption that they are familiar with basic Gramps terms and core concepts. After the article covers the task, hotlinking Gramps terms and concepts when first used in the article extends the usefulness of the article for users who are not familiar with Gramps, and may not be familiar to computing in general.

Tango-Dialog-information.png
To much repetition of introductory material is bad

Even when a workflow uses something esoteric like Attributes, a link to Attribute in the Glossary saves digressing into what Attributes are and how to create Custom Types ... all you have to say is what Attribute custom type definition should be used. It simplifies the workflow into concepts that are easier to understand rather than endless intricate steps. Also, it saves rework.

Each time the Glossary or Introductory section is improved, every article that uses those links is also improved. Linked sections ensure that the feature is described consistently and comprehensively.


Rather than explain each step in excruciating detail, it is recommended that you link unique Gramps processes to the Glossary term (preferred) or introductory section of the manual. You can link Genealogical terms to the Genealogy Glossary. Linking to Glossaries is preferred because it tersely describes the term or concept and should link to more introductory section.

Gramps-notes.png
How do I... articles don't have to be pretty or professionally written.

They just need to make correct & useful information more accessible.

Please be aware every public page may be edited by anyone. Each WikiContributor has pet projects to improve quality of pages... hotlinking, consistency of terminology, grammar, punctuation, order of presentation... all are likely to be changed.

But premature edits can step on an outline being expanded. Include a Warn note at the top if you need a few days without being interrupted by edits to complete your creative process.

Don't take offense because none is intended. When someone edits your page, they are saying that they found value in what you wrote. Enough that it is worth their time to pitch in. They might accidentally mess it up. If that happens, revert the content using the History and clarify what they misinterpreted.

Build a fresh article

Creating a wiki page can be intimidating. But you do not have to start from scratch. Gramps has template/outline that can be filled in and which has examples of much of the unique formatting. (You cut&paste from the outline's example section and discard that whole section when the page is ready for the public.)

Create a page

The MediaWiki tool has several methods start a new page when you want to add content. A good method is editing your 'user page' to insert a 'broken' internal link.

Tango-Dialog-information.png
If a core concept is missing from the Glossary...

Rather than writing foundation information into your article, consider adding a new term with the terse description to the Gramps Glossary or general Genealogy Glossary. Then link your new article to the new Glossary term. Include a link under the Glossary term to the introductory material, preferably in the Gramps wiki.

Writing in a glossary page is about the same amount of work as in an article page ... and you won't have to recreate the work for another article.


Clicking that red, broken link will display a message that no page with that name exists and offers to create a blank page.

The conventional recommendation for creating an expansion pagespace on the wiki is to create a link from another page... where the concept is only mentioned without enough explanation. Just edit the page and add a 'link' to the under-explained concept (or term) on that page.

Simply insert a line like:

[[wiki page name|my page name hotlinked label]]

While this creates a dead link, clicking on it will spawn a new pagespace where you can add the extra information. This new pagespace will show up in the indexing and Categories exactly as in the portion before the vertical bar ("&vert;"). So consider capitalization and wording. (Take a look at other pages listed in the How do I... category for a point of reference.)

This is a good method if you've built the page content offline and just want to paste in the MediaWiki markup language code. But when using the MediaWiki editor to slowly build a page from scratch, this approach adds a dead link in a highly conspicuous way. Once the first edit is saved, the link will be 'live' but might be a crude draft.

Alternately, when starting a new pages, you can create the originating link on your WikiContributor user page or discussion pages instead of from an existing page. You'll be able to find it easily while it is still a Work-In-Progress. It can be a helpful reminder to also include a link to the target page where you intend to cross-reference the finalized new content.

As a last resort, you can create a Work-In-Progress pagespace with a particular name by using the Search box in the left side bar. (Again, the name is important because it determines how the content will be listed in the Category indices.) The search will try to list articles with all the terms entered. But if there isn't a phrase match for the title, the first option will also offer a red link at the top that would create a page.

Add "How Do I..." standard form

Take advantage of the template called "Template:How do I" to insert a outline framework (with examples) for the article. That framework can be built by pasting the following lines in the newly created pagespace and saving it.

{{subst:Template:How_do_I}}

~~~~

What do these lines do?

Use the template

The double curley brackets ({{ }}) identify a named template. This uses MediaWiki's transclusion (transcribed inclusion) feature for the How do I... template to re-use the content stored in that pagename. It is similar to Server Side Includes. Think of it as a smarter version of cut&paste.

The subst:Template: before the template name uses the subclusion (substitution transcribed inclusion) feature for templates. This will cause the template content to be processed & substituted into the editable workspace as the page is saved. Because this content can now be refined without changing other pages, it is more "recycled" than "re-used".

Embed your user tag

The row of 4 tilde (˜˜˜˜) characters will add a datestamp line at the bottom with your hyperlinked WikiContributor name.

Not a valid user (talk) 23:40, 28 March 2024 (UTC)

This adds the incomplete page to the page list generated when you click "What links here" in the left sidebar on your WikiContributor page similar to the following:

 What links here:
 Page: Write a "How Do I..." Article Article

You can use this to make a work-in-progress (WIP) page list. When the page is complete enough to be made public & linked, remove the line to remove it from your WIP page list. (The Contributions link will still help you find the page but there would be more clutter.)

Possible Topics

🚧