Request for "Projects" Space in Open edX Confluence

[nsprenkle]

As part of the 2U documentation strategy and desire to design more "in the open", we'd like to have a clear place to put project-related documents in the Open edX Confluence space. The desire is to have a clear space, high in the Confluence hierarchy, to reduce cognitive effort in authoring and placing these project documents.

Project document examples:

• Project briefs & planning
• Requirements docs
• Discovery work
• Design and tech spec docs (particularly if the project spans repos)

Code documentation should probably still live in GH but it is my view that Confluence is a fine place for API/design artifacts to live while the project is in active development and those docs are largely in flux.

[nedbat]

As a slightly different (additional?) idea, what about a 2U space within the Open edX wiki, that could have team areas, etc. Other firms could also have their own spaces if they wanted to be more transparent about their structure and activities.

[feanil]

@nsprenkle 's idea fits well with how @jmakowski1123 is orgazining the OEPM space @nsprenkle what do you think of a page-tree per project under this space? Or under a Projects page in this space.

@nedbat that doesn't solve for team specific spaces but if there are teams who want to work in the open, I'm happy to discuss that as a separate matter. But feels different from Project/Feature oriented spaces.

[hurtstotouchfire]

I made a ticket for team spaces: #478

[nedbat]

@feanil I'm not sure we're all using the word "space" in the same way. I meant the Confluence space concept: an area of the wiki that can have different permissions than other spaces. 2U people could be the admins of the space, and then it could be subdivided into team pages and subtrees. Spaces are what provide the "XYZ" slug in URLs like https://openedx.atlassian.net/wiki/spaces/XYZ/pages/123456. I wasn't sure if we want to have a separate space for each team, or if that would be too many spaces.

I'm ok with whatever structure we settle on. The goal is to have a place for teams to be public and transparent.

[feanil]

@nedbat gonna respond to your comment on #478 instead of here, since I want to address @nsprenkle's concers independently from team spaces concern that you and @hurtstotouchfire have brought up.

[nsprenkle]

@feanil , I could reasonably see putting projects under the existing https://openedx.atlassian.net/wiki/spaces/OEPM/overview space, with caveats.

It seems like the current space is "higher level" than the sorts of projects I'm thinking of (e.g. if we do "grading enhancements for ORA", I thinks "ORA" might be "Product" level but not the grading enhancements).

Proposing either 1) a "Projects" folder in this space or that 2) we organize around the idea of higher level "products" and that "projects" should fit under those products. Thoughts?

[nedbat]

My idea is that the OEPM space is from the perspective of "Product owners," and represents roughly "what we plan to do and why". A "projects" area is from the perspective of "engineering managers" and represents "what we are doing." I know there is overlap and there are fuzzy boundaries....

[jmakowski1123]

@nsprenkle I think your second idea makes a ton of sense. Using your ORA example, I just created a sample "ORA Product" page and corresponding project pages. Does this example reflect what you were thinking?

[nsprenkle]

@jmakowski1123, yes, I think this is a great example. Like @nedbat said, I think there are fuzzy boundaries (e.g. my team also owns the broad concept of "grading" which overlaps with "ORA Grading" and others).

As long as we're okay with the idea of "product" being fuzzy and overlapping (for ideas like "Grading", "Course Listing Page Improvements", "Proctoring", etc.) this feels like a good place to put that info.

[jmakowski1123]

@nsprenkle I'm ok with the idea of "product" being fuzzy. I don't think we can avoid it tbh. I see what you mean with the Grading example.

Do you have a list of projects with documentation that you are in a position to share now? I'm happy to get some of the infrastructure pages built, based on what you have. You also have editing rights to create pages and nest projects within them, and please feel free to take ownership of building out the space as well. I really want this OEPM space to be owned by the community.

[nsprenkle]

@jmakowski1123, I currently have the following which I'd like to move over when you feel it's appropriate:

1. ORAs (specifically, ORA improvements)
2. ORA Staff Grader
3. Team Assignments
4. XQueue

I'm happy to make those pages, just don't want to step on your toes if you think there's a better way to organize them first :)

[jmakowski1123]

@nsprenkle I just threw together a skeleton pages, but feel free to adjust as you see fit! I put 1, 2, 3 as projects under ORA, and I created a "product" page for External Grader and put Xqueue as a project under that. If that doesn't make sense though, feel free to move it around. And for now, the product-level pages are just in alphabetical order, as they are sort of growing organically....

While we're at it, I'd like to ensure all of this work is tracked on the Open edX Roadmap as well. It will be great because the Roadmap issues can link back to these wiki spaces for access to the documentation. The Roadmap issues are meant to track at a coarse-grained level, just a high level view of all contributions-in-progress to the platform. I worked with Spencer back in May to create a Roadmap issue for ORA Staff Grader (does the work you have now continue to build on this?) and that's a good template to look at for what info I'd like to gather.

[nsprenkle]

@jmakowski1123 , we're working on figuring out what/how to do roadmapping so that's just a little further off.

For the actual movement of docs, I'm investigating tooling/workflows for exporting/importing pages so it's not a case of manually copy/pasting pages. Are you aware of any existing tooling/workflows to help with this?

[jmakowski1123]

@nsprenkle I haven't work with any, but @feanil may have?

[feanil]

As far as I know, there is no easy way to move pages from one confluence domain to another. Within a domain(openedx.atliassian..) it's easy enough but between say the 2U atlassian and the openedx one, I think the most reliable thing to do is to go into the edit mode and copy the content to a blank page on the openedx side.

[nsprenkle]

@feanil , what sort of tooling did we use for the original wiki split then?

[nsprenkle]

There's definitely a way to export existing pages as XML and, I think, installable tooling that will let that XML be reimported into another instance but I don't think this is available out of the box in vanilla Confluence.

[feanil]

Yea, the original tooling was something IT setup and was more of a backend to backend copy than a useful end user tool.

[nsprenkle]

Looks like there's a sys-admin-level space import option. Do we know folks who have this level of permissioning who could verify this exists on our instance?

Wondering if we can work through them to bulk import a bunch of our stuff into some holding space and then use the internal tools in Confluence to move those to their appropriate spaces... 🤔

[feanil]

@nsprenkle I think we've resolved this as best as we can as a ticket so closing for now. Feel free to re-open or make a new ticket if you need further help.