Using Documents, Versions and Branching ?

3dcad

I just viewed Cody's Tech Tip: Branching Designs In Onshape thanks for that.

But I would still like to dig deeper how this magnificent system is intended to use. I'm still struggling on what to model into single document.

Cody had clear and simple examples. But I have difficulties on understanding how this work on larger projects with multiple tabs.

Let's make our ultimate-collaboration-onshape-community-project to design a motorcycle as an example.
https://cad.onshape.com/documents/75b863b1b99b44a9adfe592b/w/c21d5e27e5974daab39be3d1

Roughly we have to create frame, motor, suspension, exhaust and accessories. How many documents do we need from Onshape (guys who are responsible for creating this new structure for cad) point of view?

In traditional cad each part would be separate file with different configurations (versions) and they would be used in sub-assemblies which would eventually build up the main assembly.

Onshape has changed this structure and I'm still a bit confused how should I use the new system. I have already found it to be better for simple stuff since I don't need to create assembly if I have few static parts, I can just create multipart studio. Parts and studios can be used to create assembly, mate connectors define the relations between parts - all good up to this point.

But when should I create a new document?

If we create everything in a single document (which is possible) and then we need a new version for exhaust - version is document level so it will be a new version of the complete bike.

If we create many branches (for example street / offroad setup) in the beginning then all common stuff needs to be merged between these. So it might be better to first create the bike to the point where versions begin to differ from each other.

The best though of versions I have came up is that branch is similar to having a copy of document - you can modify everything, delete or add tabs just like it would be a different document. But the big difference is that it is possible to merge branch into another which is not possible between two documents.

If we create a new document for each part or sub-assembly, team collaboration suffers and main assembly would not be linked to original parts.

My best idea would be to create document for each 'unit' (frame, motor, suspension, exhaust) and one document for main assembly which has only dumb solids of these documents to provide best performance. But updating any part would not update the bike. We are not smart enough to get it exactly right at the first time and if we were we wouldn't even need computer for this.

This is not another 'we need inter-document references' post but rather an insight for the current functionality and intensions of use behind this design.

shashank_aarya

I agree with @3dcadfor the above explained scenario. We also faced same situation while creating collaborative model with version management. In our first collaboration work users were not much familiar with version management concept. So everyone started creating the branches and versions randomly,since the intention was to check how it works. No process was defined for when should we create branch, when should we create versions etc.

So,ultimately it created a lot of confusion while creating the final assembly as there was no clear picture about a workspace which should be merged into main to get final design.In some workspaces most of the tabs were deleted based on user's requirement. While merging the workspaces it created problem as some of the tabs were important for other users. But any how by restoring through the history we managed to save some work. But this entire situation could be avoided if we could have plan this work properly before starting by defining some guidelines. So, in next collaborative work we defined some processes. We also increased communication between users for better mutual understanding to create versions, workspaces. 

I agree that it will be a tedious work to manage communication between users when it is a bigger document and number of users are on higher side similar to the above mentioned example. But we can set some guidelines for situations when to create workspaces, versions etc. as explained below.

1. For above example we can create a version when basic skeleton of bike frame is ready.
2. From this version users can take branches and create their individual designs. These branches can be reviewed periodically by any technical expert.
3. We will keep merging the branches time to time into main workspace to update the design.
4. For main workspace we can only allow merging from other workspaces, but will not allow any modification directly when design is in progress. Modification will be allowed in branches.
5. Final design should be performed in main workspace which will be the result of merging from all the branches 

So, just few points I could remember. Please suggest if I missed out anything.

Thanks

teddy_pessagno

"The best though of versions I have came up is that branch is similar to having a copy of document - you can modify everything, delete or add tabs just like it would be a different document. But the big difference is that it is possible to merge branch into another which is not possible between two documents."


This is the way I thought it would work. And I think the Tabs in each Branch just need to be cleaned up. But I don't understand how to do that yet.


Teddy_P

3dcad

Could someone from Onshape comment on this? Espescially the main question: When should I create new document?

The group who decided that part->sub-assembly->main-assembly would be better with document containing part studios and assemblies must have thought about different scenarios that could be done in single document - I would like to hear these thoughts.

Also use cases for current version/branching would be interesting to read.

I have used few times multiple branches but usually just for creating new version of one tab and that makes other tabs confusing since there is just 5 copies of same design.

ps. I don't know if anyone noticed back when Ons had free 5 docs/5 gigs, people could have created 'unlimited' amount of branches to avoid creating new docs

cody_armstrong

@3dcad I tend to lean towards putting everything in a single Document for the reasons you already mentioned. Putting everything in separate Documents without inter-Document referencing creates a lot of manual effort to keep everything up to date. It also makes it difficult to build parts that tie the different assemblies together.

You mention in your scenario you could put everything in one Document, but "then we need a new version for exhaust - version is document level so it will be a new version of the complete bike." Forgive me, I am not sure I understand what the concern here is? 

I think in your example, everything in the motorcycle that all branches shared would exist in the Main branch.  Anything specific to a branch (dirt, road, show) is modeled only in that branch.  Everyone would work together on one branch until the design reached a point that you have design variations for your different branches.

3dcad

@cody_armstrong  Thanks for taking time to answer. 

Let's assume that we could manage the whole motorcycle within one document (quite a few tabs to crawl without search).
My concern is when we create a branch for dirt and model high fenders and other stuff when we THINK everything common to all versions is ready, then someone modify main branch frame design which should affect to all branches. How do we know if we have the latest version when 'dirt' goes into production?

Second assume, if we had interdocument references; how many documents would you use on this simplified example?


About documents in general, I'm not sure if I asked my question clear enough. I'm not after help on community project nor opinions about this specific project.

When Onshape was just thoughts in developers heads, what was the scale for one document intended use?

When those thoughts were written into code and build UI around functionality (like tabs, version control, etc..)
Did you think of building a complete motorcycle into one document? Or did you think of building only a footpeg into one document? Maybe something between these?

cody_armstrong

3dcad said:

@cody_armstrong  Thanks for taking time to answer. 

Let's assume that we could manage the whole motorcycle within one document (quite a few tabs to crawl without search).
My concern is when we create a branch for dirt and model high fenders and other stuff when we THINK everything common to all versions is ready, then someone modify main branch frame design which should affect to all branches. How do we know if we have the latest version when 'dirt' goes into production?

@3dcad
Currently, the features that were added to main branch would also need to be added to the other branches. This may be laborious, but I think its less effort than managing multiple docs.  

Second assume, if we had interdocument references; how many documents would you use on this simplified example?

Me personally?  I would still use one Document.  But I think at that point its really a matter of preference.  The only advantage I see to splitting up everything into multiple Documents is its easier to search for them? We are working on ways to improve the experience when you have many tabs, so stay tuned.

About documents in general, I'm not sure if I asked my question clear enough. I'm not after help on community project nor opinions about this specific project.

When Onshape was just thoughts in developers heads, what was the scale for one document intended use?

When those thoughts were written into code and build UI around functionality (like tabs, version control, etc..)
Did you think of building a complete motorcycle into one document? Or did you think of building only a footpeg into one document? Maybe something between these?

Documents were intended as a container for your entire project.  In your example, building the complete motorcycle in one Document.  There are certainly things we can do to improve this experience.  Things like tab search, tab versioning, and better merge controls are examples of areas we could improve that would help with this workflow.

3dcad

@cody_armstrong  Thanks a lot for clearing this out, now I understand where Onshape is going and what should I request if current features are not enough. You have already listed the first improvements I've had in mind too except organizing and merging tabs to lower the amount (for example all imported original files could be found in one tab instead of having own tab for each file).

Just looked Using Onshape as Project Container Webinar, thanks for that. 

One more question about branching: Can I use a single document as a container 'per client'? I mean that branches would hold completely different tabs and designs with NO intension to merge at any time = option instead of having multiple documents / client?
If this is also intended use for Onshape, then I would like to see 'Create an empty workspace' as a new branch.

This would be a handy way to reduce the amount of documents holding just a couple of part studios or other simple stuff.
It would ease up sharing too since if the document was already shared with client new branches wouldn't require any changes and would be available for client too with same permissions as earlier.
What do you think of this use case for branches Cody? Is there any disadvantages you could think of? 

cody_armstrong

3dcad said:

@cody_armstrong  Thanks a lot for clearing this out, now I understand where Onshape is going and what should I request if current features are not enough. You have already listed the first improvements I've had in mind too except organizing and merging tabs to lower the amount (for example all imported original files could be found in one tab instead of having own tab for each file).

Just looked Using Onshape as Project Container Webinar, thanks for that. 

One more question about branching: Can I use a single document as a container 'per client'? I mean that branches would hold completely different tabs and designs with NO intension to merge at any time = option instead of having multiple documents / client?
If this is also intended use for Onshape, then I would like to see 'Create an empty workspace' as a new branch.

This would be a handy way to reduce the amount of documents holding just a couple of part studios or other simple stuff.
It would ease up sharing too since if the document was already shared with client new branches wouldn't require any changes and would be available for client too with same permissions as earlier.
What do you think of this use case for branches Cody? Is there any disadvantages you could think of? 

@3dcad None that I can think of.  

3dcad

Thanks @cody_armstrong
I will certainly give this a test drive..