Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-273

Develop and then create the organizational structure for DM Confluence space

    XMLWordPrintable

    Details

    • Story Points:
      1
    • Sprint:
      DevOps Sprint 1
    • Team:
      SQuaRE

      Description

      Before we start populating the DM Confluence space with active pages, we should define an overall organizational structure/taxonomy.

        Attachments

          Issue Links

            Activity

            Hide
            robyn Robyn Allsman [X] (Inactive) added a comment -

            K-T,
            Thanks for your comments and the earlier outline. Iteration it is. We can hash out the labels as we go along.

            Regarding the labels: Let's work on a word change here. Instead of 'controlled' what feeling do you get about 'approved'? It's not so rigid. The idea is to let folks know that the imprimatur of some body has looked over and agreed with the contents/intent of the page. The label bestows slightly more weigh, by virtue of the review status, than a random page written by a developer. Think about your trust level for random web pages vs web pages on a respected site.

            I agree that the Project controlled documents need to be archived in Docushare (or follow-on). But we have many documents which don't rise to that exacting standard yet inform the Developers about management's expectations on them. For example,the TCT decided some years back to allow upreving of selected 3rd party products to occur on a semi-annual period without reapproval by the TCT (if they first verified the uprev worked,etc). This is not an LDM controlled rule but an internal DM Policy. (Under the new division of labor, it might now be a SAT Policy instead of a TCT Policy.)

            Regarding 'living', 'versioned', 'archived' - I think we only need one designating 'versioned' to indicate that a particular page is anchored to a specific Release. We wouldn't need to designate 'versioned' on the various versioned Spaces we have; that would be redundant. Dick should respond with his sentiments on this, too.

            I view 'curator' as the person who is responsible for periodically looking over their document fiefdom for obsolete pages which either should be updated or removed. Confluence has nice searching facilities for searching on page labels. However, I wouldn't want to inhibit anyone who was willing to update a page's content on their own. I believe it's a 'Buck stops here' concept for Dick. So when he notices a disreputable page, he knows to whom to talk in order to get it fixed.

            I'm moving this Issue into Done.

            Show
            robyn Robyn Allsman [X] (Inactive) added a comment - K-T, Thanks for your comments and the earlier outline. Iteration it is. We can hash out the labels as we go along. Regarding the labels: Let's work on a word change here. Instead of 'controlled' what feeling do you get about 'approved'? It's not so rigid. The idea is to let folks know that the imprimatur of some body has looked over and agreed with the contents/intent of the page. The label bestows slightly more weigh, by virtue of the review status, than a random page written by a developer. Think about your trust level for random web pages vs web pages on a respected site. I agree that the Project controlled documents need to be archived in Docushare (or follow-on). But we have many documents which don't rise to that exacting standard yet inform the Developers about management's expectations on them. For example,the TCT decided some years back to allow upreving of selected 3rd party products to occur on a semi-annual period without reapproval by the TCT (if they first verified the uprev worked,etc). This is not an LDM controlled rule but an internal DM Policy. (Under the new division of labor, it might now be a SAT Policy instead of a TCT Policy.) Regarding 'living', 'versioned', 'archived' - I think we only need one designating 'versioned' to indicate that a particular page is anchored to a specific Release. We wouldn't need to designate 'versioned' on the various versioned Spaces we have; that would be redundant. Dick should respond with his sentiments on this, too. I view 'curator' as the person who is responsible for periodically looking over their document fiefdom for obsolete pages which either should be updated or removed. Confluence has nice searching facilities for searching on page labels. However, I wouldn't want to inhibit anyone who was willing to update a page's content on their own. I believe it's a 'Buck stops here' concept for Dick. So when he notices a disreputable page, he knows to whom to talk in order to get it fixed. I'm moving this Issue into Done.
            Hide
            shaw Richard Shaw [X] (Inactive) added a comment -

            Kian-Tat Lim "Controlled" in this sense means no change allowed except through an official DM process. Ex: coding standards, which are in the domain of the TCT (? or is it SAT?). In such a case (there aren't too many) the owner of the Confluence page (or the Group, which we haven't established yet) would have exclusive ability to edit said page. There is I think an important distinction between "controlled" and "configured" where the latter is a Project-level control, and requirements & design documents at that level live in the black hole known as DocuShare.

            Show
            shaw Richard Shaw [X] (Inactive) added a comment - Kian-Tat Lim "Controlled" in this sense means no change allowed except through an official DM process. Ex: coding standards, which are in the domain of the TCT (? or is it SAT?). In such a case (there aren't too many) the owner of the Confluence page (or the Group, which we haven't established yet) would have exclusive ability to edit said page. There is I think an important distinction between "controlled" and "configured" where the latter is a Project-level control, and requirements & design documents at that level live in the black hole known as DocuShare.
            Hide
            ktl Kian-Tat Lim added a comment -

            Looks pretty good to me. Let's try it and iterate as necessary. The one thing I still bristle a little bit at is "controlled" (and "living", "versioned", "archival"). Any really controlled documents need to be in DocuShare (or its successor). I'd say that it might be sufficient to set the expectation that a page with a designated curator/group should not be edited without the curator's permission. Other pages are "living" by default. Would that work, and reduce the number of labels?

            Show
            ktl Kian-Tat Lim added a comment - Looks pretty good to me. Let's try it and iterate as necessary. The one thing I still bristle a little bit at is "controlled" (and "living", "versioned", "archival"). Any really controlled documents need to be in DocuShare (or its successor). I'd say that it might be sufficient to set the expectation that a page with a designated curator/group should not be edited without the curator's permission. Other pages are "living" by default. Would that work, and reduce the number of labels?
            Hide
            robyn Robyn Allsman [X] (Inactive) added a comment -

            I juggled a few items around in your proposal . Read the last comment. I don't think we can cast anything in concrete until we all become comfortable with the added capabilities that Confluence gives us in comparison to TracWiki.

            A deviation from the proposal has already occurred to me based on the Confluence meetings template which automatically aggregates/indexes ALL meetings in a space. Depending on how many individual meetings are recorded, this could simplify our meeting lookup or make it unwieldy. I am leaning on trying it for a while and then splitting out into sprint buckets if the overall number of meetings gets too large (probably using a per sprint Meetings template).

            Show
            robyn Robyn Allsman [X] (Inactive) added a comment - I juggled a few items around in your proposal . Read the last comment. I don't think we can cast anything in concrete until we all become comfortable with the added capabilities that Confluence gives us in comparison to TracWiki. A deviation from the proposal has already occurred to me based on the Confluence meetings template which automatically aggregates/indexes ALL meetings in a space. Depending on how many individual meetings are recorded, this could simplify our meeting lookup or make it unwieldy. I am leaning on trying it for a while and then splitting out into sprint buckets if the overall number of meetings gets too large (probably using a per sprint Meetings template).
            Hide
            robyn Robyn Allsman [X] (Inactive) added a comment -

            Dick and I got together yesterday to discuss the layout. It remains mostly as stated by K-T but there were a few changes. Notably the contents of the DevGuide space was exchanged with the DM space. The DevGuide contents are more static and reflect the processes, rules and requirements by which the developers perform their work. The DM space reflects the instant-in-time development effort; its contents are frequently in flux.

            We considered the need for labels to annotate containers and pages to give a clue about who's responsible for curating, how often should they be reviewed for update, who may edit them. Proposals are:

            • curator: c_<name>
            • controlling group: g_<name> or g_none where name = {TCT, SAT, DMLT, APWG, DBWG, MWG, TWG}

              ; done thru permissions or a label.

            • longevity: {living (in flux), versioned (stable once Released), archival (stable)

            Confluence Spaces

            Developer User Guide Space (intended for developers of all stripes)

            • Mission Statement
            • Links to SW User Guide spaces for each release (living; controlled, c_Shaw)
            • Link to DM Guide space for internal/advanced DM developers (living, controlled?)
            • External document index (archival, curator is lead author)
              • Data Challenge reports
              • Papers
              • Presentations
              • Reviews
            • Standards and Policies (mostly: archival, controlled: g_tct
              • Glossary
              • Coding Standards
              • Procedures for: design and code review, etc
            • System Design (living, controlled, g_sat)
              • Detailed expansion of LDMs (including Requirements)
              • Implementation notes (by functional area)
            • Development environment/Tools (Some tutorial-level material e.g., illustrate the process of checking out code, creating a branch, etc. in the DM way.) Expect Developers to later add FAQs.)
              • git
              • buildbot
              • gcc, gdb
              • Python, pdb
              • Profiling and valgrind
              • doxygen/sphinx
              • Other dev tools

            DM Space (intended for internal DM developers) (living)

            • New developer information
              • Accounts
              • Machines
                • NCSA development cluster
                • lsst-web
                • lsst-db
              • Development/environment Tools (advanced usage)
              • Process (Agile, etc.)
            • Communications (living)
              • JIRA, Confluence, Stash
              • HipChat
              • Google Hangouts
              • AT Conference
              • DM Calendars
              • Mail Lists
            • DM Organization
              • DMLT (DM Leadership Team)
                • Meeting notes/action items
              • TCT (DM Technical Control Team)
                • Meeting notes/action items
              • SAT (DM System Architecture Team)
                • Meeting notes/action items
              • AWG (Applications Working Group)
                • Meeting notes/action items
              • DBWG (Database Working Group)
                • Meeting notes/action items
              • IWG (Interface Working Group)
                • Meeting notes/action items
              • TWG (Testing Working Group)
                • Meeting notes/action items
            • Per-release development information
              • Planning documents (This includes strawmans, design & implementation discussions and a pointer to final SAT approved design doc maintained in the permanent location for DM SAT design documents. These docs would be within each team’s block
              • Team organization (archival, not controlled)
                • Meeting notes/action items
              • Long code reviews (Code reviews may be considered either meetings or plain docs but belong with the Team spawning them. Except for the SAT approved designs.

            Software User Guide Spaces: Per-release documentation, one space per version; archival (with comments) for all but current

            • Installing
            • Tutorial/demo
            • Using
            • Links to doxygen/sphinx output
            • High-level descriptions of packages
              • Descriptions of meta concepts (measurement, calibration, data organization)
            Show
            robyn Robyn Allsman [X] (Inactive) added a comment - Dick and I got together yesterday to discuss the layout. It remains mostly as stated by K-T but there were a few changes. Notably the contents of the DevGuide space was exchanged with the DM space. The DevGuide contents are more static and reflect the processes, rules and requirements by which the developers perform their work. The DM space reflects the instant-in-time development effort; its contents are frequently in flux. We considered the need for labels to annotate containers and pages to give a clue about who's responsible for curating, how often should they be reviewed for update, who may edit them. Proposals are: curator: c_<name> controlling group: g_<name> or g_none where name = {TCT, SAT, DMLT, APWG, DBWG, MWG, TWG} ; done thru permissions or a label. longevity: {living (in flux), versioned (stable once Released), archival (stable) Confluence Spaces Developer User Guide Space (intended for developers of all stripes) Mission Statement Links to SW User Guide spaces for each release (living; controlled, c_Shaw) Link to DM Guide space for internal/advanced DM developers (living, controlled?) External document index (archival, curator is lead author) Data Challenge reports Papers Presentations Reviews Standards and Policies (mostly: archival, controlled: g_tct Glossary Coding Standards Procedures for: design and code review, etc System Design (living, controlled, g_sat) Detailed expansion of LDMs (including Requirements) Implementation notes (by functional area) Development environment/Tools (Some tutorial-level material e.g., illustrate the process of checking out code, creating a branch, etc. in the DM way.) Expect Developers to later add FAQs.) git buildbot gcc, gdb Python, pdb Profiling and valgrind doxygen/sphinx Other dev tools DM Space (intended for internal DM developers) (living) New developer information Accounts Machines NCSA development cluster lsst-web lsst-db Development/environment Tools (advanced usage) Process (Agile, etc.) Communications (living) JIRA, Confluence, Stash HipChat Google Hangouts AT Conference DM Calendars Mail Lists DM Organization DMLT (DM Leadership Team) Meeting notes/action items TCT (DM Technical Control Team) Meeting notes/action items SAT (DM System Architecture Team) Meeting notes/action items AWG (Applications Working Group) Meeting notes/action items DBWG (Database Working Group) Meeting notes/action items IWG (Interface Working Group) Meeting notes/action items TWG (Testing Working Group) Meeting notes/action items Per-release development information Planning documents (This includes strawmans, design & implementation discussions and a pointer to final SAT approved design doc maintained in the permanent location for DM SAT design documents. These docs would be within each team’s block Team organization (archival, not controlled) Meeting notes/action items Long code reviews (Code reviews may be considered either meetings or plain docs but belong with the Team spawning them. Except for the SAT approved designs. Software User Guide Spaces: Per-release documentation, one space per version; archival (with comments) for all but current Installing Tutorial/demo Using Links to doxygen/sphinx output High-level descriptions of packages Descriptions of meta concepts (measurement, calibration, data organization)

              People

              Assignee:
              robyn Robyn Allsman [X] (Inactive)
              Reporter:
              ktl Kian-Tat Lim
              Reviewers:
              Kian-Tat Lim
              Watchers:
               
              Votes:
              2 Vote for this issue
              Watchers:
              0 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  CI Builds

                  No builds found.