Skip to end of metadata
Go to start of metadata

Confluence page structure and best practices

Space Structure

The following rules should be observed by each confluence user in the RS confluence space:

  • Most of the writing should be organized by topic, i.e. under the RS Components top page
    Pages that are not related to a specific business functionality go under another top page, eg 00 Core or 0 General
  • RS Components is split by component: [01 Core], 02 UI and Navigation, 03 Security, etc
  • For each component page "<NN> <Component>" you can have subpages such as:
    • <Component> Req Items: subset of initial business requirements, created BM in the ResearchSpace Business Requirements & Specification (see RS Docs, restricted to Stage3 requirements. All text about a component is gathered in one page and duplications are removed. Requirements are extracted based on commitments in RS Technical Offer and Best and Final Offer. Each requirement has these attributes:
      • Requirement ID - unique requirement identificator. It will be used for referencing the requirements, as well as for requirements traceability during the project.
      • Requirement priority - shows the iteration based on the project plan, for which the requirement is planned for development. For example RS3.2 means that a requirement will be implemented during the second iteration of Stage3, RS4 means that a requirement will be implemented during Stage, RS? means that a requirement is not yet prioritized. Requirements could be reordered during the project and their priorities would change then also.
        This list with requirements is not a final one, and could be changed, extended or reduced within project continuance.
        Before each project iteration, based on these initial high level business requirements and their priorities, will be created a detailed functional specification.
    • <Component> Concepts: conceptual ideas and considerations that have not crystallized into a specification yet. Please contribute any idea or new requirement you have. See Annotation Concepts as an example
    • <Component> Tools: research and notes on existing open source tools/ approaches/ ontologies. See Search Tools as an example
    • <Component> Spec RS3.1: crystallized and detailed requirements, use cases, state chart diagrams for the current sprint. This is the functional specification addressed to the developers.
    • <Component> <Others>: any other pages if the information cannot be classified in any of the above pages

Page Titles

  • Page titles should Stand Alone. This means that when you look at it (eg in the search autocomplete), you should be able to tell what is it about
    • At the same time, page titles should be as short as possible
  • Page titles should be use only ASCII (English). Don't use colons, Cyrillic, longdash etc. Else the URL does not show the page title but only the pageId.
    • Should NOT have a lot of URL-special chars, so the URL is more readable. Eg "Sitemap - future" is better than "Sitemap (future)".
  • If you have a bunch of existing sibling pages and you add another, name the new one similar to the old ones

Version Notation

A "tag" at the end of the page name in parentheses, to indicate its status:

  • RS3.1 : the first sprint
  • RS3 : in scope, involves several sprints
  • RS3.? : in scope, sprint not yet determined
  • RS4 : out of scope: functionality and thinking for next stage

Page Structure

  • write each separate topic on its own page
  • write a question/explanation inside the page, instead of a comment below the page. The reader shoudln't have to pore through discussions to get the meaning. The page should read as smoothly as possible
  • add {toc} at the top if there's more than 1 section
  • use bullets liberally: I think they make better structure than running paragraphs


  • if the page has a single (or few) DOC/XLS/PDF attachment, use the {viewdoc}, {viewxls}, {viewpdf} macros to display the file directly in the page. Add a short description (what is the file about) on top.
  • You can easily move attachments between pages: click the paper-clip on top, select Properties for the appropriate attachment, Specify the page you want to move the attachment to.
  • if you have a bunch of shots, put section heading before each shot, and a paragraph of explanation, eg
    h1. Project Administrator Overview Dashboard


Re Annotation Spec (changes)

  • leave blank line before table, else it's indented as per prev bullet
  • use || instead of | for table header cells (be that row or col header)
  • use Table Sharper icon on Wiki Markup toolbar to align table columns

Screen Shots

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.