Tags:
documentation1Add my vote for this tag create new tag
, view all tags

Where to Put Official Docs Missing in TWiki Distribution

DakarRelease is offloading a lot of documentation from the distribution's TWiki web to TWiki.org. The question is where to put all this documentation in a consistent way. Discussions in the Bugs web stranded (such as Bugs:Item1058) or have been removed without considering a permanemt place (such as Bugs:Item1468)

ALERT! NOTE: This topic is tracked as Bugs:Item1480 and is marked as "Requirement".

Requirements:

  • Use one and only one web for official docs moved out of the distribution
  • Mark those docs as "official but not in distribution"
  • Decide permanent place (web)
  • Decide set of permanent topics linked from distribution
  • Link them from distributed docs

There are three possible places:

TWiki.org's TWiki web:

TWiki.org's Codev web:

  • smile Already a lot of TWikiOn topics there with platform specific installation instructions
  • frown Large web where search can be difficult
    • Can be mitigated with good links and categories
  • frown Mixing developers/spec content with documentation

TWiki.org's Support web:

  • smile Logical place for administrators to go to get help
  • frown Mixing knowledge base entries with official docs

Based on this I think the TWiki web is the best place to store the official docs. This gives us also the opportunity to refactor good platform specific installation docs. The TWiki web already has an included header to identify "official topics that are shipped with the distribution". We can define one additional included header that identifies "official topics that are not shipped with the distribution".

-- PeterThoeny - 23 Jan 2006

Some issues with that:

  1. TWiki is the doc web for the installation that runs twiki.org. As such, it will contain many docs that should not be edited by community, because they duplicate what is in everyone's installations, and we don;t want divergence.
  2. TWiki web here needs a lot of defactoring to be useable with DakarRelease. A simple search throws up a lot of outdated or irrlevant content.
    • There is content from earlier versions, it is marked as such. TWiki.org needs to be upgraded to Dakar, at that time the TWiki web will be updated. -- PTh
Just a suggestion, but wouldn't it be better to start again wiuth a fresh web? That way you can simply move across the docs that are relevant, and keep TWiki web as read-only (as it is intended to be in any installation)

-- CrawfordCurrie - 23 Jan 2006

On starting a fresh web, yes, I will create a TWiki04 web once Dakar is released. It will be the TWiki 4.0 web for reference, edit locked down. See existing TWiki01, TWiki02, TWiki03 webs.

-- PeterThoeny - 23 Jan 2006

I didn't mean a fresh web per release. I meant a fresh web for documentation - e.g. "Documentation" web.

CC

I'm quite happy to help make this happen, but a decision is needed now otherwise I can't.

-- CrawfordCurrie - 25 Jan 2006

Lynnwood and I are discussing this. We will post the result tomorrow.

-- PeterThoeny - 26 Jan 2006

Then it is too late for me to help. OK.

-- CrawfordCurrie - 26 Jan 2006

PeterThoeny and I spend some time on the phone this afternoon trying to sort out the various options and ramifications on this issue and came to following recommendations:

  1. The TWiki web on TWiki.org be re-designed to serve two main functions:
    1. Documentation entry-point for all versions of TWiki.
      • This would be accomplished through new set of DocumentationCategory topics (plus revised introductory text on TWiki.WebHome) that provides a clear navigation pathway to all "official" TWiki documentation, including that included in each of the respective releases (each in it's own web as described under #2 below), as well as "supplemental" documentation that expands on the the distributed documentation and applies across releases.
      • The DocumentationCategory topics will exist only on TWiki.org (i.e. they are not part of the distributed documentation) but are referenced within the distrubted documentation. The names for "entry topics" addressing major subjects such as InstallingTWiki and UpgradingTWiki would not change from release to release in keeping with CoolURIsDontChange, but would be updated with current links to all documentation on that subject.
      • In addition to the category tags, these topics whould be distinguished from other topics in the TWiki web by a colored banner.
    2. Documentation development for the upcoming release. In other words, after Dakar is released, the TWiki web will be used for development of the Edinburg documents.
      • These documentation-topics-under-development would also be distinguished by a colored banner.
  2. A reference copy of the documentation from each major release will be kept in separate webs named after the release. E.g. TWiki01, TWiki02, etc.
    • These reference webs would be non-editable.

We went back and forth some between the idea of re-organizing the TWiki web along the lines described above versus creating a new "Documentation" web. The approach described above of organizing the documentation could as easily be applied within a Documentation web as in the TWiki web. However, this should be settled before Dakar release so the links within the distributed docs don't change. We finally settled on using the TWiki web in the interest of 1) not creating another web (and thereby further complicating the organization of TWiki.org), and 2) providing consistency with earlier conventions for documentation links that referred back to the TWiki web.

-- LynnwoodBrown - 27 Jan 2006

I started with the categorization of the TWiki web. See overview TWiki.WebHome. Topics are categorized into these types:

Each type has a color coded header with explanation. See EngineRoom for details.

-- PeterThoeny - 30 Jan 2006

Edit | Attach | Watch | Print version | History: r9 < r8 < r7 < r6 < r5 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r9 - 2006-01-30 - PeterThoeny
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.