Structure guidelines

Issue of version compliance

New versions of Open CASCADE might change structure and interfaces of packages in Open CASCADE. To deal with this, the following approach is persued:

  • code samples and interface descriptions should always include the Open CASCADE versions, they are known to work with and -if possible- also versions, they are known to not work with.
  • Articles who have becomen obsolete (because they describe an interface removed in an newer version of Open CASCADE, for example), have to include a notice about the Open CASCADE version, at which they have becomen obsolete.
  • Articles specific to Open CASCADE version x.y.z which have to be replaced (and solely in that case!) by a new version will be duplicated and the copy is moved to namespace "x-y-z". The copy moved to "x-y-z" includes a notice and a link to the current version of the article.

(TODO: We could need macros or something like that for such version notices as mentioned above - so they look similiar throughout the wiki)

Wiki namespaces

The purpose of namespaces is to be able to restrict an article search to a specific class of articles. For example, using namespaces you can list automatically all registered projects by simply listing all articles in namespace "projects". The namespace structure should not be used excessively to structure articles by content, because there are always articles fitting into more than one content category. For content description, the tag mechanism is much more appropriate!

  • wiki articles codifying the wiki contents and guidelines, as well as describing how to use the wiki
  • projects articles describing specific projects using Open CASCADE
  • x-y-z articles containing details specific to Open CASCADE version x.y.z - articles should only be moved into such a namespace, if there's a version specific to a newer version of Open CASCADE!

Tags

The quality of a wiki is directly linked to the ability of visitors to find the searched information quickly. The tag mechanism is able to greatly enhance this access. Therefore it is wished that article authors try to add a reasonable number of tags to their articles. Reasonable means

  • sticking to existing tags, where possible
  • creating meaningful new tags, where needed
  • not overusing tags (otherwise they would lose their significance)

There's an article listing existing tags and when to use them.

Describing Open CASCADE

The articles describing OCC are structured into 4 categories:

  • Overviews are helping the reader to gain an oversight over what's there
  • HowTos are helping users to use Open CASCADE effectively and properly
  • Annotations are adjuncts to the official documentation, pointing out some relevant (usually important) fact missing in the official version
  • Essays are detailed explanations of specific substructures of OCC - a class, a package or something else

There might be articles fitting into more than one of those categories above. To adress this issue, the assignment to categories is done via tags. Please use one ore more of the following tags, if you're creating an article about Open CASCADE:

  • overview
  • howto
  • annotation
  • essay

Main articles

Front page

The front page should

  • welcome visitors and tell them what this wiki is about
  • attract people to browse the wiki
  • give users starting points to dive deeper into the wiki