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 DONE, too.
    • ALERT! Presently, the topics on this Foswiki site are not synchronized with SVN. Therefore, the updated content has to be transfered seperately.
HELP 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

  • HELP 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.
    • ALERT! 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:
  • 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

Old topic New topic Revised Foswiki SVN Comments
  BeginnersStartHere DONE frown, sad smile DONE  
  FileAttachments DONE frown, sad smile DONE  
  GoodStyle DONE frown, sad smile DONE  
  ShortHand DONE frown, sad smile DONE directly linked to WikiSyntax -- SK
  ProposalTopicsAndWebs (proposal), ProposalWorkingTopics (proposal) DONE frown, sad smile frown, sad smile For some time after Foswiki 1.0 release, TWikiTopics would be substituted by ProposalTopicsAndWebs and completed by ProposalWorkingTopics. The aim is to separate the general topics and webs explanation from topic manipulation. -- SK
  TwentyMinuteTutorial DONE frown, sad smile DONE  
  WebChangesAlert DONE frown, sad smile DONE  
  WikiCulture DONE frown, sad smile DONE  
  MailerContrib DONE frown, sad smile DONE  
  DocumentGraphics DONE frown, sad smile DONE  
  FrequentlyAskedQuestions DONE DONE DONE  
  GlossaryOfTerms DONE DONE DONE  
  WelcomeGuest DONE DONE DONE  

DONE = ok REFACTOR = presently in process frown, sad smile = pending


2. Power User

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

Old topic Proposal Revised Foswiki SVN Comments
  WikiSyntax DONE frown, sad smile DONE  
TextFormattingFAQ         Deleted and substituted by WikiSyntax; WikiSyntax was completed with missing content from this topic -- SK
  EditingShorthand DONE frown, sad smile DONE  
  TextFormattingRules DONE frown, sad smile DONE  
  UsingHTML DONE frown, sad smile DONE  
  MacrosQuickStart DONE frown, sad smile DONE  
  System.Macros DONE frown, sad smile DONE  
  AccessControl DONE frown, sad smile DONE  
  DataForms DONE frown, sad smile DONE  
  System.Skins DONE frown, sad smile DONE  
  SkinBrowser DONE frown, sad smile DONE  
  SkinTemplates & TemplateTopics DONE frown, sad smile DONE  
  System.Plugins DONE frown, sad smile DONE  
  System.Contribs DONE frown, sad smile DONE IMHO needs some additional explanation and differenciation from Addons & Plugins, but for 1.0 the SVN version is ok. -- SK
  ContributedAddOns DONE frown, sad smile DONE IMHO needs some additional explanation and differenciation from Contribs & Plugins, but for 1.0 the SVN version is ok. -- SK
  ManagingTopics DONE frown, sad smile DONE  
ManagingWebs ProposalManagingWebs frown, sad smile frown, sad smile frown, sad smile see also discussion at RedesignManagingWebs
  ManagingUsers DONE frown, sad smile DONE  
  MetaData DONE frown, sad smile DONE  
  FormattedSearch DONE frown, sad smile DONE  

DONE = ok REFACTOR = presently in process frown, sad smile = pending


3. Administrator (for various platforms)

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:

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:

move 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


Topic revision: r51 - 02 Apr 2010, WillNorris
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy