Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History

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 [RS Architecture] or [0 Project Management]
  • 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

Attachments

  • 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

Tables

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

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