View Source

{excerpt}Confluence page structure and best practices{excerpt}
{toc}

h1. 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

h2. 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

h2. 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

h1. 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

h1. 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
{noformat}h1. Project Administrator Overview Dashboard{noformat}

h1. Tables

Re [Annotation Spec] ([changes|https://confluence.ontotext.com/pages/diffpages.action?pageId=9505134&originalId=9505236])
- 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

h1. Screen Shots

- take the shots as PNG, without browser chrome and empty space (eg use [http://www.snagit.com])