This article details the Standard Instructive Article Model utilized in Wikibon. It should be used by contributors and reviewers to capture instructive knowledge in textual form.
What Is the Standard Instructive Article Model?
It's a convention for prioritizing the capture and consumption of instructive knowledge. Contributors and editors should follow this convention to keep the experience costs of creating, reviewing, and applying Wikibon content as low as possible. After reading mature instructive articles, readers should be able to:
- describe the solution.
- envision the type of customization work they'll have to undertake to adopt the solution.
- generally frame a business case for adopting the solution.
- generally frame a project plan for adopting the solution.
How does the Standard Instructive Article Model Work?
To help contributors maximize the quality of the instructive content, and minimize the time devoted to the mechanics of prioritizing and structuring the instructive content, the model provides simple guidelines regarding what types of content to include, where to include it, and how much to include.
Using the Mediawiki tools for capturing, formatting, and linking content, these articles are created, edited, and incorporated into Wikibon's catalog of collective wisdom. Generally, Wikibon will apply the peer-review protocol promulgated by Wikipedia, the largest and most successful site for peer-review knowledge in the world.
Instructive articles should be written, reviewed, edited, and added to by contributors with first-hand knowledge of the solution domain. In other words, contributors should have participated in performing the actions of the solution, and not just be familiar enough with a solution to comment on it.
Once posted to Wikibon, articles complying with this model will be easier to improve, link, and use.
What Are the Impacts of Using the Standard Instructive Article Model?
Instructive content usually is derived from specialized knowledge and is captured utilizing a specialized lexicon. The processes of both capturing and consuming instructive knowledge is made difficult by this specialization. Contributors have to decide how much detail is enough, while consumers seek cues to determine if they can use the article to help solve their problem.
Use of the Standard Instructive Article Model is intended to:
- Maximize the productivity of contributing and using Wikibon content.
- Ensure that articles capture the right level of detail.
- Help consumers "learn" how to read Wikibon articles.
- Faciliate a civilized peer-review protocol.
- Maximize placement of Wikibon articles in search engines.
How to Use the Standard Instructive Model to Write a Wikibon Article
Contributors should contribute what they know and can. In other words, the Standard Instructive Article Model does not presume completeness at initial posting: the beauty of a wiki is that subsequent posts and other contributors can iteratively complete the model and thereby improve the article.
In general, initial contributions should include a title, a solution description, and a simple recipe for how to adopt a solution. Mature posts will include additional information on how a solution works, the impacts of using the solution, and greater detail on adoption processes. Each of these is described below.
Dimensions of an article
There are three dimensions to consider when writing a Wikibon article:
- The Noun Dimension - what is it?
- The Lifecycle Dimension – what stage is it at?
- The Task Dimension – how is it done?
The Noun Dimension
Here, we’re focused on the transformative capabilities being invested in by organizations and individuals. Typically, they’ll be vogue, hot, or whatever. These nouns will be organized under headings dictated by institutional realities: market factors, organizational factors, etc. Thus “Storage” is an “institutional” heading because there is a storage market that typically sells storage-related tools and services to storage buyers looking to build storage-related capabilities.
Article topics should be selected based on relevance to the community.
The Lifecycle Dimension
Any investment in a business or individual capability typically runs through six distinct phases, independent of scale: (1) analyze; (2) design; (3) build; (4) implement; (5) operate; and (6) exit. Each of these phases is associated with different, yet coherent, forms of risk, skills, tools, artifacts, etc. Without dictating methodological details, almost all methods pay homage to this simple formulation.
For example, the process of investing in an “optimize permanent information storage” business capability, which is the essence of “tiered storage,” can easily be characterized in terms of the above simple investment/actuating process.
Articles should be selected and written to fit clearly into one of each of the six lifecycle phases.
The Task Dimension
Although Lifecycle phases are distinct, they nonetheless share common classes of administrative tasks that must be executed at some scale to be regarded as “complete”: (1) planning; (2) preparing; (3) performing; (4) promoting; and (5) parting. Each of these activities is associated with different roles, responsibilities, and rules for engaging resources. Different investments will require that a different scale of attention be applied to these administrative activities, including “not perform” for specific administrative tasks.
Table 1 shows the three dimensions of an article with details of the lifecycle and task dimensions.
Briefly, these task classes can be described as follows:
- Planning – the activities associated with the first step of getting work done. Namely establishing broad goals, a rough scope, a conceptual game plan and a subjective sizing effort of costs and benefits to determine if the project is feasible relative to other priorities of the organization.
- Preparing – these activities generally involve identifying a champion, choosing a team, identifying more specific tasks that have to get done to execute on the work plan, lining up resources, considering incentives, identifying critical success factors/risks and setting up a governance structure.
- Performing – Actually doing the work and executing on the work plan. The set of tasks associated with performing includes problem solving, tracking progress and other day-to-day project management activities.
- Promoting – getting the solution to be adopted by the organization, transferring knowledge, maintaining the system, etc.
- Parting – thoughtfully winding down the effort when the value of the effort is exceeded by the cost of maintaining the effort and is deemed a poor return of no strategic value to the organization.
Articles should address each of these tasks in some amount of detail.
The following sections describe the specific content within a Wikibon article. Contributors should also understand the basics of Applying the Wikibon lifecycle model to develop articles.
Article Title
The article's title should take a <gerund> <solution name> form, thereby succinctly describing the actions covered in the article. For example, "Writing a Wikibon Article Using the Standard Instructive Article Model." When creating the initial link to the entry, remember to use this same title form in the originator page.
Paragraph #1: Who and Why
The first paragraph should include three types of information:
- A basic statement of the article's purpose (single sentence)including its intended audience
- What the article will help the reader accomplish (one or a few sentences)
- A basic statement on the structure of the article (one or a few sentences)
Paragraphs 1a-->1c: Executive Summary
The Executive Summary is a compact synopsis of the most salient points in the piece. It should include a thumbnail assessment of the task at hand with valuable extracts of the piece, prominently included. These might include key benchmarks, costs, benefits, risks, and high level recommendations.
Paragraphs #2 and #3: What is the Solution
The next few paragraphs should provide "What Is It?" information on the solution. This section must be written in sufficient detail, while minimizing the use of technical jargon, to ensure that non-specialists can determine the relevance of the article to their problem. At minimum, two paragraphs are necessary:
- A paragraph describing the solution.
- A paragraph describing the attributes of the problem the solution is trying to solve.
Paragraphs #4-8: How Does the Solution Work
Successfully adopting a solution requires the availability and management of an array of resources. While classes of solutions inevitably share common features, users will encounter different problems which will lead to distinct adoption activities. To help readers quickly frame a mental model of how they might use the solution (as described in the previous section) given their particular set of circumstances, this section highlights solution characteristics that will most likely dominate customization decisions. Four paragraphs should be provided, one covering each of the following.
Intrinsic Mechanics
Provides a basic explanation of how the solution works. Enough detail should be provided so that the reader could begin comparing different forms of the solution in terms of key assessment characteristics.
Technology Dependencies
Details the technological pre-requisites of the solution in written or list form. Where appropriate, links to greater detail on key technology dependencies should be provided.
Skills Dependencies
Details the inventory of skills necessary to successfully adopt and operate the solution. Where appropriate, links to greater detail on key skill dependencies should be provided.
Organizational Dependencies
Adoption always takes place in an organizational context. Here, the organizational attributes required for successful adoption should be articulated (e.g., who should champion, risk taking or risk averting)
Paragraphs 9-12: What Are the Impacts of Using the Solution?
The next section outlines the costs and benefits of adopting the solution. Ideally, these would be captured in list form, with subsequent paragraphs providing a deeper explanation of each point, as appropriate.
This section should include three "case example" paragraphs that characterize best case, typical case, and worst case conditions for adopting the solution.
After reading this section, readers should be able to formulate, in broad terms, a "business case" for the solution, including likely returns, likely costs, and likely risks.
Paragraphs 13+: How to Adopt the Solution
The crescendo for a Standard Instructive Article Model entry is this section, which lays out the steps generally required to successfully adopt the solution. Depending on the nature of the solution and the energy of the contributing community, the information in this section will range from a simple recipe to articulating a process structure to a comprehensive project template. In all cases, however, the section should capture detail on who does what and when.
The activities / tasks articulated in Table 1 should be used as a guideline for writing this section.
How do you know when you're done?
Wikibon uses a maturity model for assessing the level of completeness of an article. There are four levels of maturity defined (see Figure 2) :- Level 1 - stub
- Level 2 - usable as a standalone document
- Level 3 - usable as part of a process within the lifecycle
- Level 4 - Mature and considered complete
--PBurris 12:59, 12 October 2006 (CDT)