Task Teams » Simplify Documentation Task Team

Summary:	Simplify and improve distributed documentation
Team lead:	Team lead
Participants:	DavidWolfe
Status:	Discontinued

Goals

• simplify documentation by looking for opportunities to consolidate topics, distill content, and remove outdated or otherwise irrelevant comments
• improve documentation by:
  • correcting typos (ignoring differences in International English and U.S. English)
  • correcting grammar and punctuation
  • normalizing "style," defined as writing styles, person, punctuation, etc.
  • rewriting passages as needed to make them understandable by non-programmers (may require help of programmers to understand what is intended)
  • Where additional instruction is needed (i.e., where advanced admin knowledge is needed), either provide that instruction or provide links to it elsewhere, as commented by CarloSchulz, 08 Nov 2007 in AdminSkillsAssumptions.
• Classify and Organize the Supplemental Documents so they are easily accessible.
  • Develop and populate a better, user-driven:
    • FAQ library
    • Cookbook library
    • "Special platforms" library * Add introductory pages for new users (current pages quickly dive into interface details)

[Please add additional goals as needed]

Required Powers

Information Useful to Conduction this Task

• One thing I noticed is that Codev has a lot of tips and cookbooks buried in some topics. Whenever I found them, I tag them with "extract_stuff", so IMO you should check out those topics and extract these tips to the official docs. This serves two purposes: helps keeping Codev clean and enhances the TWiki documentation. -- RafaelAlvarez - 12 Sep 2008
  • ExtractToDocsSearch lists these tagged topics. As content is extracted into documentation, please remove the extract_stuff tag, so the topics will be removed from the list.

Discussion

I have been using "extract_stuff" as a catch-all tag... I'll split it in "extract_doc" and "extract_idea", so you need only to focus on the "extract_doc" tag.

-- RafaelAlvarez - 13 Sep 2008

As one of several who spends inordinate amounts of time answering the same questions over and over again on IRC, I beg you for a decent FAQ that doesn't require god-powers to add entries to.

-- CrawfordCurrie - 13 Sep 2008

There is a TWikiFAQ though not so friendly in different ways.

-- KwangErnLiew - 13 Sep 2008

Good ideas about the FAQs. I'm curious about what the community believes are the deficiencies of the TWikiFAQ. We've built several FAQs topics in our TWiki that are often-used and FAQs more easily perused and used. For example, we always name FAQ Topics keeping in mind the list will be sorted alphabetically, and we always put a bold title at the front of the topic, so the list calls out the listed questions by theme. We've created separate FAQs, each one with a different focus, and a topic which lists all the FAQs in one place. Then we put this list on the WebHome page to give everyone quick access to the FAQs they need. (Screencap below shows sorted FAQs with titles.) Would some things like that make the FAQs here more useful?

-- DavidWolfe - 13 Sep 2008

This is definitely an improvement. WIth a lot of FAQs it would be helpful to add grouping.

The "Answer" link I find redundant, because it should be a list of links. For example:

I would also prefer to have this in place instead of the tips contrib.

Part of the documentation is also the answered questions in Support web. There we also find a FAQ. These 'FAQs' are more interactive than the 'finished' ones in TWiki web. We could also learn from Yahoo Answers how to show lists of answers:

What I find more urgent - and probably just needs a small fix - is the consolidation of documentation webs. Visit Main Web and in the left bar see the list of webs under Documentation. Which one to pick? Can we say Latest documentation and Previous releases ?

-- ArthurClemens - 13 Sep 2008

Would it be appropriate, then, to create a topic containing a TOC of sorts for the previous version docs, then replace the LeftBar links with a single link to that topic that says "Previous Versions?" If so, should that change be made in all webs' LeftBars, or just Main?

-- DavidWolfe - 13 Sep 2008

It depends. TWiki Web has more documentation than the distributed TWiki versions. But TWiki.WebHome has a couple of links at the top that we can use in the left bar as well.

-- ArthurClemens - 13 Sep 2008

I found a topic that may be useful to transform into a official document on how TWiki could be used: CollaborationSituations

-- RafaelAlvarez - 14 Sep 2008