Task ideas

Structure for updated Documentation

Documentation

Process for updating documentation

1. Pick out one of the documents that are indicated as still pending and mark them in the first column as being edited while you are updating them.
2. Leave the content of the original topic as is and create a proposal for the new content in the Sandbox web, picking Proposal + the original topic name as temporary topic name. Example:
   ProposalWikiSyntax for the updated topic corresponding to the original WikiSyntax or
   ProposalGoodStyle for the updated topic corresponding to original GoodStyle
3. Once you finished the revision in the proposal topic, mark the topic as ok. Leave it there for some time for discussion.
4. If there are no further observations from the comunity, the updated content will be transfered to this Foswiki site and into the core documentation on SVN and replace the original topics. The topics that were transfered (either to this Foswiki site or to SVN) will be marked with , too.
   • Presently, the topics on this Foswiki site are not synchronized with SVN. Therefore, the updated content has to be transfered seperately.

Topics that do not show an old topic name any more were already revised and uploaded to SVN. They might not be updated on the Foswiki website though!

Guidelines/suggestions for initial documentation revision

• The objective for Foswiki 1.0 is not to rewrite the complete documenation - this is a large term target. The aim for Foswiki 1.0 rather is to have a working, updated documentation based on the existing topics.
• Revising terminology - Refer to rebranding and the new terminology.
  • A huge amount of rebranding has been done in SVN, so you can get the original content with the included rebranding from there, too. Although you do not have SVN access configured on your local computer, you can access it at http://svn.foswiki.org/. Surf to http://svn.foswiki.org/trunk/core/data/System/ and look for the text file with the topic name, e.g. AccessControl.txt when you are looking for the AccessControl topic.
• Changing references to Supplemental Documents on twiki.org:
  • See if parallel topic has been created at SupplementalDocuments and change reference.
• Replacing "TWiki" with "Foswiki" - Where "TWiki" is used to refer to the platform, replace with "Foswiki". Where it is used to refer to the local installation, replace with %WIKITOOLNAME%.
• See the language usage guide for guidance on language and HowToWriteBetterCopy for some general guidelines.

Topics and proposals

1. User

For a guide that covers the basic needs of normal users, see ProposalUserGuide.

Up to now, this guide is composed of existing, refactored topics and is still missing the following information that would have to be included by new topics:

1. What is a wiki, and particularly Foswiki, good for?
   • Short overview of usages
   • Concentrate on tasks people want to do, and how Foswiki could improve that

---

2. Power User

For a guide that covers the basic needs of power users, see ProposalPowerUserGuide. This guide is composed of existing, refactored topics.

---

3. Administrator (for various platforms)

• Overview of Foswiki technology, including
  • data storage capabilities
  • authentication capabilities
• Minimum requirements on,
  • administration skills
  • software packages, excluding extension requirements.
• Guide on Foswiki installation and configuration, including
  • webserver configuration (e.g. Apache)
  • filesystem configuration, i.e. file and directory ownership and permissions
  • unicode and translation support
  • extensions
  • templates
  • See documents at SupplementalDocuments!
    Please do not do any changes on the SupplementalDocuments without having coordinated with KennethLavrsen before. The documents listed there are under heavy construction and refactoring.
• FAQ
• Existing topics that might serve as basis, but may need refactoring:
  • TWikiSystemRequirements; shall be renamed to SystemRequirements
  • TWikiInstallationGuide; shall be renamed to InstallationGuide
  • TWikiUpgradeGuide; shall be renamed to UpgradeGuide
  • TWikiUserAuthentication; shall be renamed to UserAuthentication
  • TWikiSiteTools; shall be renamed to SiteTools

4. Developer

• Overview of,
  • not only programmers
  • what it takes to be a developer, include sign up procedure
  • subversion access
  • procedure for QA and release
• Technical overview of Foswiki, includes the structure of the application
• Coding standards/conventions: how to write quality code
• Usable APIs
• FAQ
• Existing topics that might serve as basis, but may need refactoring:
  • SvnRepository
  • DevelopersBible
  • TWikiFuncDotPm; shall be renamed to ???
  • TWikiScripts; shall be renamed to CommandAndCGIScripts
  • TWikiCss; shall be renamed to CascadingStyleSheets

Discussion

I am proposing to split up the present TWikiDocumentation into two individual user guides - one for normal user and one for power users. See also ProposalUserGuide and ProposalPowerUserGuide.

-- SebastianKlus - 16 Dec 2008 - 17:33

---

moved here from DocumentationTaskTeam and subsequently edited by WillNorris

---

Review existing documentation

Focus on 4 areas of the documentation.

1. User
2. Power User
3. Administrator (for various platforms)
4. Developer

Separate and sort existing documentation

According to the following criteria (refactor if necessary):

• Basic user documentation - this documentation is shipped with the Foswiki download package and focuses on the main tasks of users and power users like creating and editing topics, webs, user administration, etc. These topics are located in the System web (also referred to as Release Documentation).
• Admin documentation - includes everything that has to do with installation and configuration of Foswiki. This part of documentation must be available online as when installing Foswiki the internal documentation cannot be accessed. Appropiate documents shall be moved to the Support web (also referred to as Site Documentation).
• Developer documentation - all around development. Shall be online available at the Development web (also referred to as Site Documentation). References from internal docu to external docu is required.

Preparing and guiding TWiki users

TWiki users will ask themselves what has changed. Lots of TWiki names have been replaced, and topics may not be found immediately. These users need a proper introduction and guidance. Admins will be reluctant to upgrade if their users are not helped sufficiently.

---

I think it would be useful to also create screencasts. They are quite easy to do. Perhaps target screencasts at users and create heavier, more detailed documentation for admins and developers?

-- MartyBrandon - 14 Nov 2008 - 04:51

---

Lots of extensions have minimal documentation and do not even clearly describe what they can do. For instance, it is hard to see whether an extension will work on the current release. Also a visual illustration would help a lot. Is this something this team wants to take on? For instance by providing guidelines, examples and hands-on changes?

-- ArthurClemens - 22 Nov 2008 - 11:09

---

I would like to begin creating some instructional slide presentations that would be posted to SlideShare. I'd planned to use these to educate the users (mostly computer-phobic biologists) of my own site, but was now hoping to make them into general Foswiki documentation. Are there any objections to this? Things I should do to coordinate?

Take a look at ProposalBeginnersStartHere. The idea of this topic is similar - doing a slide presentation to educate new users. Perhaps some parts are useful for your presentation. -- SebastianKlus - 18 Dec 2008 - 14:03

-- MartyBrandon - 18 Dec 2008 - 05:49

---

What about adding forms to documentation topics, containing the following information for classification purposes:

Summary	One-liner for topic content
Directed towards	Drop-down list with Users, PowerUsers, Administrators, Developers
TopicClassification	Drop-down list with Release documentation and Site documentation

This way, structuring and classifying the different topics becomes much easier. As gadget, each different type of topic (according to the type of users) we could add a logo at the top of a topic like it is already used on developers documentation.

-- SebastianKlus - 18 Dec 2008 - 14:34

---

Does anyone believe it is worth to maintain the old topic names and just put a link to the new topic name? Like:

This topic was moved to NewFoswikiTopic.

This way, users switching from TWiki to Foswiki and being used to the old topic names on the one hand are aware of the change in the topic name and on the other hand do not get lost looking for a specific topic.

-- SebastianKlus - 18 Dec 2008 - 14:34

What about including a map of old topic names to the new in some sort of meta-documentation? That would give an at-a-glance explanation of how things had been rearranged. My own experience in starting with TWiki was that there was a lot of documentation, but you had to spend considerable time searching around and piecing it all together. Guides organized around a specific goal, such as altering the appearance, were most helpful.

-- MartyBrandon - 19 Dec 2008 - 13:57

---

FoswikiBookProposal.

---

Extensions.Testing.PackageViewTemplate

---

reworking of System.EmptyPlugin documentation topic template. do we really need a file list? if so, can we put it in a twisty? how about the history in a twisty? standardize sections like "how to tell if it's working" and links to samples in the Sandbox web. the entire page is ripe for reworking.

-- WillNorris - 02 Apr 2010

---