Wishlist: "Knowledge Base" feature
| Affects | Status | Importance | Assigned to | Milestone | |
|---|---|---|---|---|---|
| Launchpad itself |
Triaged
|
Low
|
Unassigned | ||
Bug Description
Short summary: A formal "knowledge base" feature would bridge the gap between "Bugs," "Answers," and external project documentation that never gets written.
My main experience with Launchpad is through Ubuntu and Ubuntu-related projects, but I think this is a general suggestion, so I'll place it here for comment. Ubuntu is the "flagship" Launchpad project, so please consider all references to it in that context. "Issue" as used here encompasses all possibilities of "bug," "question," "quirk," or "feature" that could possibly require documentation.
A lot of criticism directed at Ubuntu relates to the quality of documentation and community support. Other projects are also not immune to the phenomenon of documentation lagging reality (or never getting written at all). In the FOSS "bazaar," it is often difficult to find an authoritative answer to even the most common questions. In fact, the ability to locate documentation can be observed to degrade based on the prevalence of an "issue," as puzzled users are doomed to propagate discussion and theories that will then be indexed for web search.
I propose that a "Knowledge Base" feature in Launchpad would help remedy this situation by allowing projects to maintain and improve their 'institutional memory,' and also ease the process of producing effective documentation.
First, to explain what I am talking about, let me define the properties (and responsibilities) of a "Knowledge Base" article:
* Is a single written article that conveys true and accurate information;
* Makes every effort to ensure the information is consistent with documentation / "best practices";
* Identifies and acknowledges any inconsistencies with, or deficiencies in documentation;
* Identifies which versions of a project the information is known to apply to;
* Identifies which versions of a project the information may (but has not been formally confirmed) apply to;
* Is subject to Wiki-like revision by anyone on Launchpad;
* Is subject to editorial review by project subject-matter experts, with reviewed versions favored.
This is in contrast to a "bug" in Launchpad terms, which is intended to produce discussion leading to modification or correction of software, or an "Answer," where a specific, individual question is handled (with exactly as much detail and expertise as emerges in the discussion).
As it stands, Ubuntu and other Launchpad projects are attempting to achieve this goal through external wikis, but there are some problems. Foremost, the people most familiar with the bugs are active on Launchpad, but may not have access to wikis that have been locked down against spam and vandalism. Next, wikis being wikis, determining how current and trustworthy a given article is can become a complicated game of review that each individual reader must undertake.
If, instead, bug participants were invited to contribute to a KB article when their bug is closed, and others are free to author an entry when they feel they can speak with authority, the available documentation would increase dramatically and duplication of effort could be largely avoided. These articles could then be reviewed as the designated project personnel can get to them, and either approved, corrected, or discarded.
Metadata could also be included as to the reviewer's opinion of the quality/
Here is a contrived "user story" to illustrate the potential usefulness:
1. Bob is struggling to add a user to his Ubuntu system and, in desperation, posts to a forum.
2. Alice replies to Bob, explaining `vipw` and attaching a Bash script she wrote to edit the desired login image into gdm.conf.
3. Bob, impressed with this arcane knowledge, logs into Launchpad and creates KB entry #321 for the Ubuntu project, "Adding a user." The system forces him to identify the version he knows it applies to (8.10) and lets him separately specify which he thinks it may apply to (all versions past and present).
4. Eve, a designated reviewer, stumbles upon the article a few weeks later and rewrites it to document the GNOME user management facilities. The article gets marked as reviewed and trustworthy, as far as these things go.
5. Trent, a more advanced user, stumbles on Eve's revision and is chagrined that there's now no mention of command-line user management. He drafts up KB #322, "Adding a user from the command-line," and edits #321, preserving it but adding the cross-reference. Regular users still see Eve's edit when conducting a basic search, with a "There is a newer, but unreviewed version of this article." link at the top. When viewing Trent's version, they're warned "This article has not been reviewed. Click here to see the last reviewed version."
6. Eve gets around to reviewing Trent's modification, and approves it. KB #321 is now as useful as it can be (at least until someone adds new xrefs for the Kubuntu and Xubuntu users!).
7. Months later, the project is preparing to cut a new release. Zoe, another designated reviewer, runs a search for entries marked as applying, or maybe applying, to it. There are 5,000 results, so she triages them by refining the search by popularity and component. #321 is a very popular article, and the user management GUI changed quite a bit for this hypothetical release, so she edits #321 one last time and creates a new article for 9.04. By the time the release is out, the top 500 topics have been brought up to date, and users are already submitting articles documenting the other new features of the release. [The KB articles on "hardware known to work with 9.04" and "hardware known to have problems with 9.04" are quite popular, as well.]
...
I think that makes the case. For smaller projects, developers might choose to write about features as they introduce them, preserving that information in the KB instead of (or together with) putting it on a weblog or project page where it might expire or become inaccessible.
| Diogo Matsubara (matsubara) wrote | #1 |
| Changed in launchpad: | |
| status: | New → Incomplete |
| floid (jkanowitz) wrote | #2 |
| floid (jkanowitz) wrote | #3 |
| affects: | launchpad → launchpad-foundations |
| Changed in launchpad-foundations: | |
| importance: | Undecided → Low |
| status: | Incomplete → Triaged |
| floid (jkanowitz) wrote | #4 |
| floid (jkanowitz) wrote | #5 |
| Matthew Paul Thomas (mpt) wrote | #6 |
| floid (jkanowitz) wrote | #7 |
Launchpad Answers have a FAQ feature <https:/