<p>In my opinion the software version should not be updated if the documentation changes, while the software itself does not change.</p>

<p>I do not prefer to use different versioning for technical documentation and software as the docs are related to a certain software version. Different versioning will result in confusion.</p>

<p>In conclusion, one could use the same versioning, but if only the doc is updated one could add metadata, like 1.2.3-20171017. By using metadata one could still see that the doc belongs to version x of the software and one could also see that the doc has been updated.</p>

CC BY-SA 3.0
2017-10-17T16:03:36.363Z
Updating the doc should be a patch increase in the software IMHO
Tensibai
CC BY-SA 3.0
2017-10-17T15:35:34.457Z
2017-10-17T15:35:34.457Z
030
<p>It seems to me that your customers should be dictating the versioning. Both teams seem to be heading towards the same thing but only partially understanding the customer impact. For development, when they significantly re-architect components, there is risk because this could corrupt data or leave core features in a malfunctioning state - this should be reflected by a major version number change.</p>

<p>This doesn't mean much to marketing - everything looks the same, so why would the customer notice this change? No need to reflect this as a major change... unless you are a developer, in which case you risk a huge amount support interactions over those bugs. </p>

<p>Similarly marketing is looking at the user interface with the assumption that with a significant overhaul to the GUI, customers might get lost or hate the new user interface. This could lead to significant support interactions helping customer navigate the new UX, so should be reflected as a major version number change to the customer. There is a lot of risks there... Unless you are developer. Then this is purely cosmetic. Everything is still functioning the same on the back end. </p>

<p>So it seems you need to decide what it is that you feel version numbering is for.</p>

<ul>
<li>Are version numbers used to signal risk to customers?</li>
<li>What source control system are you using</li>
<li>Does Development even need version numbers <em>at all</em> or are commit IDs sufficient?</li>
<li>Does Development plan features against version numbering for the purposes of setting deadlines?</li>
</ul>

<p>Depending on the answers, it might be ideal to use a single version numbering system led by marketing - but marketing will need to do a better job of understanding the risks of under-the-hood changes. If this is needed as a designator for setting deadlines for change integrations, then two version numbering systems might be approperite:</p>

<p>Side note: git tags would be great for any version numbering scheme you have mentioned.</p>

CC BY-SA 3.0
2017-10-17T20:59:15.533Z
2017-10-17T20:59:15.533Z
James Shewey
<p>A common problem at my company is versioning. We follow a versioning system <em>formatted</em> very similar to semantic versioning (but not by <em>definition</em>). Our current versioning is not only used by development, but also by marketing/sales in their release notes, advertising, etc. Often times, there are conflicts as to what the versioning should be. What the development team defines as a major change (non-backwards compatible api change) is often not considered a "major" change by marketing. Other times, marketing will push to increment the major because their is a significant customer workflow change, but from a development perspective, the change is very insignificant (often times just an application code patch). </p>

<p>I am pushing heavily to separate our versioning into two distinct systems, a business versioning and a technical versioning system. This would allow both teams to define their own rules for versioning that best suites their needs. While the feedback in general is positive, some of the concerns are the confusion that this will cause, in our cross team communication and ticketing systems. </p>

<p>What are some of the complications of having two versioning systems? What are some of the benefits of a separation? What kind of impact will this have on the teams and the company as a whole?</p>

CC BY-SA 3.0
2017-10-17T15:31:43.267Z
Isn't using a different scheme for each a viable alternative option to disambiguate business and software versions ?
Tensibai
CC BY-SA 3.0
2017-10-17T15:38:51.730Z
Correct. That is what I'm referring to. The push back however is that there will be confusion between teams when referring to different versions in cross team communications such as documentation, feature requests, etc.
Preston Martin
CC BY-SA 3.0
2017-10-17T16:04:57.210Z
There's no reason, let the marketing have a fancy prefix for their taste and keep the actual version after, for Soft 2.3.5, business version 2k17-2.3.5 should do, business could then upgrade to 2k18-2.3.6 for the case you were talking about without impacting the semver of the software.
Tensibai
CC BY-SA 3.0
2017-10-20T06:34:33.150Z
Your software isn't a library or API of some sort, right, but a GUI application?
Xiong Chiamiov
CC BY-SA 3.0
2017-10-20T16:54:57.473Z
@XiongChiamiov Our products are an assortment of web and desktop applications. Some of them also utilize or include a library/API that would be versioned as well.
Preston Martin
<versioning>
Creating a Separate Technical and Business Versioning System
Preston Martin
# Creating a Separate Technical and Business Versioning System

(Asked by: username_0 on 2017-10-17)

A common problem at my company is versioning. We follow a versioning system *formatted* very similar to semantic versioning (but not by *definition*). Our current versioning is not only used by development, but also by marketing/sales in their release notes, advertising, etc. Often times, there are conflicts as to what the versioning should be. What the development team defines as a major change (non-backwards compatible api change) is often not considered a "major" change by marketing. Other times, marketing will push to increment the major because their is a significant customer workflow change, but from a development perspective, the change is very insignificant (often times just an application code patch).

I am pushing heavily to separate our versioning into two distinct systems, a business versioning and a technical versioning system. This would allow both teams to define their own rules for versioning that best suites their needs. While the feedback in general is positive, some of the concerns are the confusion that this will cause, in our cross team communication and ticketing systems.

What are some of the complications of having two versioning systems? What are some of the benefits of a separation? What kind of impact will this have on the teams and the company as a whole?

**Tags:** versioning

> **Comments:**
> **username_1**: Isn't using a different scheme for each a viable alternative option to disambiguate business and software versions ?  
> **username_0**: Correct. That is what I'm referring to. The push back however is that there will be confusion between teams when referring to different versions in cross team communications such as documentation, feature requests, etc.  
> **username_1**: There's no reason, let the marketing have a fancy prefix for their taste and keep the actual version after, for Soft 2.3.5, business version 2k17-2.3.5 should do, business could then upgrade to 2k18-2.3.6 for the case you were talking about without impacting the semver of the software.  
> **username_2**: Your software isn't a library or API of some sort, right, but a GUI application?  
> **username_0**: @XiongChiamiov Our products are an assortment of web and desktop applications. Some of them also utilize or include a library/API that would be versioned as well.  

---

## 2 answers

### Answer by username_4 on 2017-10-17. Score: 3 | Accepted answer

It seems to me that your customers should be dictating the versioning. Both teams seem to be heading towards the same thing but only partially understanding the customer impact. For development, when they significantly re-architect components, there is risk because this could corrupt data or leave core features in a malfunctioning state - this should be reflected by a major version number change.

This doesn't mean much to marketing - everything looks the same, so why would the customer notice this change? No need to reflect this as a major change... unless you are a developer, in which case you risk a huge amount support interactions over those bugs.

Similarly marketing is looking at the user interface with the assumption that with a significant overhaul to the GUI, customers might get lost or hate the new user interface. This could lead to significant support interactions helping customer navigate the new UX, so should be reflected as a major version number change to the customer. There is a lot of risks there... Unless you are developer. Then this is purely cosmetic. Everything is still functioning the same on the back end.

So it seems you need to decide what it is that you feel version numbering is for.

* Are version numbers used to signal risk to customers?
* What source control system are you using
* Does Development even need version numbers *at all* or are commit IDs sufficient?
* Does Development plan features against version numbering for the purposes of setting deadlines?

Depending on the answers, it might be ideal to use a single version numbering system led by marketing - but marketing will need to do a better job of understanding the risks of under-the-hood changes. If this is needed as a designator for setting deadlines for change integrations, then two version numbering systems might be approperite:

Side note: git tags would be great for any version numbering scheme you have mentioned.


---

### Answer by username_3 on 2017-10-17. Score: 1

In my opinion the software version should not be updated if the documentation changes, while the software itself does not change.

I do not prefer to use different versioning for technical documentation and software as the docs are related to a certain software version. Different versioning will result in confusion.

In conclusion, one could use the same versioning, but if only the doc is updated one could add metadata, like 1.2.3-20171017. By using metadata one could still see that the doc belongs to version x of the software and one could also see that the doc has been updated.

> **Comments:**
> **username_1**: Updating the doc should be a patch increase in the software IMHO  

---

