Tuscany cwiki & Website Structure (TUSCANY) edited by haleh mahbod
Page:
http://cwiki.apache.org/confluence/display/TUSCANY/Tuscany+cwiki+%26+Website+Structure
Changes:
http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=56590&originalVersion=17&revisedVersion=18
Content:
---------------------------------------------------------------------
The Apache Tuscany Project Website ([http://apache.tuscany.org]) content is
authored collaboratively by the Tuscany community. The content authoring
and publish takes place in the following steps:\-
* This authoring of content happens on the *Tuscany Space* of the Confluence
based Apache Wiki - [http://cwiki.apache.org/confluence/display/TUSCANY].
* Content thus created is exported as html, based on change activity, to the
Confluence based export site - [http://cwiki.apache.org/TUSCANY].
* Finally the confluence based html content is synced at regular intervals over
to the project's public site [http://incubator.apache.org/tuscany].
There is more information at the end of this page on how content is
synchronized from the Wiki to the public site.
[comment: can we remove the following parag?]
Since the Wiki content forms the backbone for the public website content, it is
important that the community adheres to some community accepted common
guidelines when authoring content on the Wiki, to help in consistency and
maintainability of the content. The objective of this page is to record
these guidelines.
[comment: and replace with]
Since the wiki content forms the backbone for the public website content, its
structure is documented here to help keep it maintainable.
h2. Wiki Content Authoring
The Apache Tuscany project consists of three subprojects - SCA, SDO and DAS
each of which is implemented in C+\+ and Java. These subprojects and
their implementations have different documentation and download pages. There is
a lot of information that gets shared on the website related to all these
projects and it is essential to have a clear structure to help ease the
administration, modification and maintenance of the website. Here is a
proposal for how the information on cwiki can be organized with this goal in
mind.
[Need to make sure community is in agreement before we make this the guideline
- so, here is the proposal].
h3. Content Structure
Tuscany cwiki is divided into two *logical* spaces.
# *Tuscany General space:* this is where you will find general Tuscany
information, for example community, blogs, documentation and downloads for
Tuscany. The root of the pages under this category is 'General
Info'. The pages under 'General Info' contains information like : Home,
SCA Overview, SDO Overview, DAS Overview. All pages categorized under 'Genral
Info' the use the same navigation menu.
# *Tuscany Subproject space:* There is a 'logical' space for each subproject
under Tuscany. For example, SCA Java, SDO Java, SCA Native, etc. When under a
subproject, you'll only find information about the subproject. Each subproject
uses its own menu (which is similar for all subprojects) to navigate through
pages for that subproject. This means navigation remains constant when
traversing through pages of a subproject.
# *Tuscany Menus :* Another category of pages are the various 'Menus' that are
used. These have been isolated as another sub-tree of content to help in
independent organization of Menu options. Under this subtree titled
'Menus' is organized all the sets of Menu options that appear on the Navigation
pane on the left.
h4. Wiki tree structure
Tuscany
* Home
** SCA Overview (general)
*** SCA Java (subproject)
(on) You will find a similar structure as SCA Java under all other subprojects
(SCA Native, SDO Java, DAS Java, ...)
**** *SCA Java Subproject Documentation Menu* \- All publishable documentations
are under this
**** *SCA Java Releases* \- All release download pages for the subproject are
under this
**** *SCA Java Work-in-progress* \- This is place holder for work in progress.
It is recommended that all in progress discussions such as new release
discussion, documentation in progress, etc. be put under here. When a document
is ready, it can be moved to the appropriate location in the tree.
*** SCA Native (subproject)
** SDO Overview (general)
*** SDO Java (subproject)
*** SDO Native (subproject)
** DAS Overview (general)
*** DAS Java (subproject)
*** DAS Native (subproject)
** General Info (general) - holds information applicable to all projects. For
example, Events, documentat/download, community, etc.
** Menus - You will find all menus under here
*** General - You will find general menu here
*** Subproject Menus - You will find subproject specific menus here
Therefore, content on the wiki page can logically go into
1) General
2) Subproject
3) Work in progress subtree of the subprjoect
[Comment: Can we remove the following section? It is covered with the above 3
lines]
h3. Want to add content to the website?
# Before adding any content to the wiki take a look at the content tree
structure at
[http://cwiki.apache.org/confluence/pages/listpages-dirview.action?key=TUSCANY]
and identify a node in the tree where the content could best fit. To
start with you could identify if the content falls under general or under a
specific subproject or under a specific implementation of a subproject.
Then under this you could further categorize if the content is to do with
'Technical Documentation' or 'Release' and so on.
# Having decided on a position for the content page in the content tree
strucuture ensure that the 'Parent Page' is properly set to the identified
position (page).
# If any part of a content is likely to be reused under different contexts and
hence in different pages, then abstract such reusable content into a separate
page and include it in the various contexts (using the include macro) instead
of duplicating the content across contexts.
# Since all pages should have a relevant Navigation Menu when composing a page
divide the page into two columns (under a section) with the Menus going into
the first column and the page content going into the second column. Use
the following as a template for all pages.
{noformat}
{section:border=false}
{column:width=15%}
{include: <enter the name an existing Menu page from the 'Menus' category of
pages>}
{column}
{column:width=85%}
<<enter page content here>>
{column}
{section}
{noformat}
# If there are going to be a set of pages that are likely to be created with
the same specific set of menus then a easy way of creating them as per the
above template is to go and first create a template page at
[http://cwiki.apache.org/confluence/pages/templates/listpagetemplates.action?key=TUSCANY]
using the above snippet with approprieate Menu pages substituted.
Subsequently when create a page go to
[http://cwiki.apache.org/confluence/pages/templates/listpagetemplates.action?key=TUSCANY]and
exercise the "Create page from template" option against the template just
created. This will result in a new page with the appropriate sections and
menus and the content can be right away filled in.
# If a new set of Menu options are to be created, then create a menu page for
this under the 'Menus' category. You can also choose to create a set of
menu options reusing the existing Menu pages and 'including' them as required.
h1. How to deploy to convert Cofluence Native to Apache Tuscany website
We use an autoexport plugin that automatically converts Confluence's native,
and dynamically generated content into a static HTML version that gets exported
to the Tuscany website which is located at apache.tuscany.org.
!WebsiteStructure.jpg!
*Resources*
* Website SVN :
[https://svn.apache.org/repos/asf/incubator/tuscany/site/site-publish/]
* Exported website : Apache minutaur machine at \-> /www/confluence-exports
* Tuscany website : Apache minotaur machine at \-> /www/apache.tuscany.org
---------------------------------------------------------------------
CONFLUENCE INFORMATION
This message is automatically generated by Confluence
Unsubscribe or edit your notifications preferences
http://cwiki.apache.org/confluence/users/viewnotifications.action
If you think it was sent incorrectly contact one of the administrators
http://cwiki.apache.org/confluence/administrators.action
If you want more information on Confluence, or have a bug to report see
http://www.atlassian.com/software/confluence
