Create new "Guides" section on www.gerritcodereview.com

[David Shevitz]

During the last user conference, I learned that many Gerrit maintainers and users would like improve the on-boarding experience.

To help with that effort, I'd like to create a Guides section on our website, www.gerritcodereview.com. The purpose of this section is to be a sort of documentation hub where users can learn about the Gerrit workflow, read tutorials for specific scenarios, and learn about best practices.

The reason I want to create a different site: I think it is important to have at least a subset of our documentation that is independent of the core Gerrit repo. First, this would allow us to more easily track analytic data so we can learn about what topics users are most interested in. Also, having content that is independent of a specific Gerrit release would allow us to get content updates to users at a faster rate.

I've already created a change to see what this section might look like. One thing that has been pointed out: we need to figure out how to handle previous versions of guides--perhaps by following a model similar to what we do for the product documentation. 

I'm interested in what the Gerrit community thinks--if you have a moment, please take a look at the change and let me know your thoughts.

Thanks!

[Sven Selberg]

First let me say that I applaud the effort to rewrite the tutorials.

" I think it is important to have at least a subset of our documentation that is independent of the core Gerrit repo."

It's a tempting thought, but given the non-backwards-compatibility of Gerrit there will (IMM) never be a documentation that is truly independent of the core Gerrit repo with the respect to specific versions.

You could probably have some things like "how to download the change-id hook" and "how to download a patch-set" that will probably be stable for a foreseeable future but that IMM would lead to a fragmentation of the tutorials that would not make it easier to follow the tutorials and know where to look for specific items or solutions. Independent documentation would be in the form of a more dictionary capacity (what is a Change-Id and how is it used by Gerrit) and things from a higher level of abstraction such as "The benefits of code review" and "The philosophy behind Gerrit".

"First, this would allow us to more easily track analytic data so we can learn about what topics users are most interested in."

True, although i suspect that a large percentage of Gerrit users will just google the problem and end up on gerrit-review, go-review or android-review anyway so getting some data from googles opensource instances would give you pretty good data that you can start collecting now. I say this because as a Gerrit admin (on a Gerrit that sadly enough sports a pretty archaic version ATM) I am regularly confronted with users who have read about new features they want to use on those sites and are asking why it doesn't work on our Gerrit. Also it's a well utilized pattern "If problem -> google it" and our instance is not indexed in googles search engines (I think) so most users end up in puclic Gerrit instances. While this could be seen as a reason to remove all documentation from the Gerrit repo I would like to point out that with documentation specific to the Gerrit version we are currently running served by Gerrit we (as Gerrit admins) can direct our users to documentation that works for them.

"Also, having content that is independent of a specific Gerrit release would allow us to get content updates to users at a faster rate."

* This content will more often than not reference Gerrit versions that are not sported by users in the wild, even if the feature is there the interfaces will in many cases differ from previous versions (See my previous comment suggesting that documentation independent of a specific Gerrit release being something of a mirage)

* If we have the tutorials in the gerrit project, the latest tutorials will always be available at sites that runs something very close to "master" (gerrit|go|android-review.googlesource.com) within a matter of days? weeks? (not fully aware of the upgrade schedule).

If my assumptions that there cannot be a documentation that is truly version agnostic, at least I feel the need to give my users documentation that fits the version they are working with. If we don't have any sort of version control of our documentation and don't maintain it in the context of gerrit releases (stable-2.14, stable-2.15 etc.) but in a single branch in a different repo the task of offering version specific documentation with respect to any other version than latest master is practically impossible. 

Since you commented in the change that large portions in the tutorial you wrote are more or less copies of the old tutorials, and you frequently link back to those tutorials you have adopted all the issues of the old tutorials _and_ you have a clear dependency to specific Gerrit versions (which I think is inevitable). Even with a quick glance through I found references to two Gerrit versions, 2.14.5 and 2.15 one of which doesn't exist yet (when this is written). This is not meant as a criticism of your change but to me it is an indication that a "version independent" documentation is not really possible.

One other thing is that historically in (I believe) all project there has been the problem of documentation of this sort lagging behind, barely kept alive by a handful of unsung heroes. With the documentation in the same Repository as the source code at least the effort to update the documentation decreases. Partly because you don't have to maintain two changes but mostly that you can check what the documentation says by issuing a simple ' git grep -i <feature specific term>'. One might suggest that the developers will have to step up to the challenge "or similar" but the truth is that we are all humans and most of us have fast paced jobs where things like "updating the homepage git with corresponding changes" is very often down prioritized when services starts to burn and your customers gathers outside your office with torches and pitchforks.

So to conclude:

I'm totally in favor of reworking the tutorials but with the setup you are describing they will (IMO) only be truly valuable for googles opensource instances and for the few that also have something close to latest master deployed (which is virtually impossible for us that have limited staff resources and a commitment to 99.99% uptime).

Best regards

Sven

[Luca Milanesio]

On 31 Oct 2017, at 09:24, Sven Selberg <sven.s...@axis.com> wrote:

First let me say that I applaud the effort to rewrite the tutorials.

" I think it is important to have at least a subset of our documentation that is independent of the core Gerrit repo."

It's a tempting thought, but given the non-backwards-compatibility of Gerrit there will (IMM) never be a documentation that is truly independent of the core Gerrit repo with the respect to specific versions.

You could probably have some things like "how to download the change-id hook" and "how to download a patch-set" that will probably be stable for a foreseeable future but that IMM would lead to a fragmentation of the tutorials that would not make it easier to follow the tutorials and know where to look for specific items or solutions. Independent documentation would be in the form of a more dictionary capacity (what is a Change-Id and how is it used by Gerrit) and things from a higher level of abstraction such as "The benefits of code review" and "The philosophy behind Gerrit".

I would say a bit more: the Gerrit workflow concept overall hasn't changed much over the years. Honestly, *that* is the major obstacle of newbies to Gerrit.

They are coming from the Pull-Request paradigm, which is very different to the Gerrit one.

"First, this would allow us to more easily track analytic data so we can learn about what topics users are most interested in."

True, although i suspect that a large percentage of Gerrit users will just google the problem and end up on gerrit-review, go-review or android-review anyway so getting some data from googles opensource instances would give you pretty good data that you can start collecting now. I say this because as a Gerrit admin (on a Gerrit that sadly enough sports a pretty archaic version ATM) I am regularly confronted with users who have read about new features they want to use on those sites and are asking why it doesn't work on our Gerrit. Also it's a well utilized pattern "If problem -> google it" and our instance is not indexed in googles search engines (I think) so most users end up in puclic Gerrit instances. While this could be seen as a reason to remove all documentation from the Gerrit repo I would like to point out that with documentation specific to the Gerrit version we are currently running served by Gerrit we (as Gerrit admins) can direct our users to documentation that works for them.

"Also, having content that is independent of a specific Gerrit release would allow us to get content updates to users at a faster rate."

* This content will more often than not reference Gerrit versions that are not sported by users in the wild, even if the feature is there the interfaces will in many cases differ from previous versions (See my previous comment suggesting that documentation independent of a specific Gerrit release being something of a mirage)

* If we have the tutorials in the gerrit project, the latest tutorials will always be available at sites that runs something very close to "master" (gerrit|go|android-review.googlesource.com) within a matter of days? weeks? (not fully aware of the upgrade schedule).

If my assumptions that there cannot be a documentation that is truly version agnostic, at least I feel the need to give my users documentation that fits the version they are working with. If we don't have any sort of version control of our documentation and don't maintain it in the context of gerrit releases (stable-2.14, stable-2.15 etc.) but in a single branch in a different repo the task of offering version specific documentation with respect to any other version than latest master is practically impossible. 

Since you commented in the change that large portions in the tutorial you wrote are more or less copies of the old tutorials, and you frequently link back to those tutorials you have adopted all the issues of the old tutorials _and_ you have a clear dependency to specific Gerrit versions (which I think is inevitable). Even with a quick glance through I found references to two Gerrit versions, 2.14.5 and 2.15 one of which doesn't exist yet (when this is written). This is not meant as a criticism of your change but to me it is an indication that a "version independent" documentation is not really possible.

One other thing is that historically in (I believe) all project there has been the problem of documentation of this sort lagging behind, barely kept alive by a handful of unsung heroes. With the documentation in the same Repository as the source code at least the effort to update the documentation decreases. Partly because you don't have to maintain two changes but mostly that you can check what the documentation says by issuing a simple ' git grep -i <feature specific term>'. One might suggest that the developers will have to step up to the challenge "or similar" but the truth is that we are all humans and most of us have fast paced jobs where things like "updating the homepage git with corresponding changes" is very often down prioritized when services starts to burn and your customers gathers outside your office with torches and pitchforks.

So to conclude:

I'm totally in favor of reworking the tutorials but with the setup you are describing they will (IMO) only be truly valuable for googles opensource instances and for the few that also have something close to latest master deployed (which is virtually impossible for us that have limited staff resources and a commitment to 99.99% uptime).

Best regards

Sven

On Monday, October 30, 2017 at 7:07:26 PM UTC+1, David Shevitz wrote:

During the last user conference, I learned that many Gerrit maintainers and users would like improve the on-boarding experience.

To help with that effort, I'd like to create a Guides section on our website, www.gerritcodereview.com. The purpose of this section is to be a sort of documentation hub where users can learn about the Gerrit workflow, read tutorials for specific scenarios, and learn about best practices.

The reason I want to create a different site: I think it is important to have at least a subset of our documentation that is independent of the core Gerrit repo. First, this would allow us to more easily track analytic data so we can learn about what topics users are most interested in. Also, having content that is independent of a specific Gerrit release would allow us to get content updates to users at a faster rate.

I've already created a change to see what this section might look like. One thing that has been pointed out: we need to figure out how to handle previous versions of guides--perhaps by following a model similar to what we do for the product documentation. 

I'm interested in what the Gerrit community thinks--if you have a moment, please take a look at the change and let me know your thoughts.

Thanks!

--
--
To unsubscribe, email repo-discuss...@googlegroups.com
More info at http://groups.google.com/group/repo-discuss?hl=en

---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Sven Selberg]

On Tuesday, October 31, 2017 at 1:38:37 PM UTC+1, lucamilanesio wrote:

On 31 Oct 2017, at 09:24, Sven Selberg <sven.s...@axis.com> wrote:

First let me say that I applaud the effort to rewrite the tutorials.

" I think it is important to have at least a subset of our documentation that is independent of the core Gerrit repo."

It's a tempting thought, but given the non-backwards-compatibility of Gerrit there will (IMM) never be a documentation that is truly independent of the core Gerrit repo with the respect to specific versions.

You could probably have some things like "how to download the change-id hook" and "how to download a patch-set" that will probably be stable for a foreseeable future but that IMM would lead to a fragmentation of the tutorials that would not make it easier to follow the tutorials and know where to look for specific items or solutions. Independent documentation would be in the form of a more dictionary capacity (what is a Change-Id and how is it used by Gerrit) and things from a higher level of abstraction such as "The benefits of code review" and "The philosophy behind Gerrit".

I would say a bit more: the Gerrit workflow concept overall hasn't changed much over the years. Honestly, *that* is the major obstacle of newbies to Gerrit.

They are coming from the Pull-Request paradigm, which is very different to the Gerrit one.

I concede that it was not very clear, but to me "Gerrit Workflow" is included in "The philosofy behind Gerrit". So I agree.

 

"First, this would allow us to more easily track analytic data so we can learn about what topics users are most interested in."

True, although i suspect that a large percentage of Gerrit users will just google the problem and end up on gerrit-review, go-review or android-review anyway so getting some data from googles opensource instances would give you pretty good data that you can start collecting now. I say this because as a Gerrit admin (on a Gerrit that sadly enough sports a pretty archaic version ATM) I am regularly confronted with users who have read about new features they want to use on those sites and are asking why it doesn't work on our Gerrit. Also it's a well utilized pattern "If problem -> google it" and our instance is not indexed in googles search engines (I think) so most users end up in puclic Gerrit instances. While this could be seen as a reason to remove all documentation from the Gerrit repo I would like to point out that with documentation specific to the Gerrit version we are currently running served by Gerrit we (as Gerrit admins) can direct our users to documentation that works for them.

"Also, having content that is independent of a specific Gerrit release would allow us to get content updates to users at a faster rate."

* This content will more often than not reference Gerrit versions that are not sported by users in the wild, even if the feature is there the interfaces will in many cases differ from previous versions (See my previous comment suggesting that documentation independent of a specific Gerrit release being something of a mirage)

* If we have the tutorials in the gerrit project, the latest tutorials will always be available at sites that runs something very close to "master" (gerrit|go|android-review.googlesource.com) within a matter of days? weeks? (not fully aware of the upgrade schedule).

If my assumptions that there cannot be a documentation that is truly version agnostic, at least I feel the need to give my users documentation that fits the version they are working with. If we don't have any sort of version control of our documentation and don't maintain it in the context of gerrit releases (stable-2.14, stable-2.15 etc.) but in a single branch in a different repo the task of offering version specific documentation with respect to any other version than latest master is practically impossible. 

Since you commented in the change that large portions in the tutorial you wrote are more or less copies of the old tutorials, and you frequently link back to those tutorials you have adopted all the issues of the old tutorials _and_ you have a clear dependency to specific Gerrit versions (which I think is inevitable). Even with a quick glance through I found references to two Gerrit versions, 2.14.5 and 2.15 one of which doesn't exist yet (when this is written). This is not meant as a criticism of your change but to me it is an indication that a "version independent" documentation is not really possible.

One other thing is that historically in (I believe) all project there has been the problem of documentation of this sort lagging behind, barely kept alive by a handful of unsung heroes. With the documentation in the same Repository as the source code at least the effort to update the documentation decreases. Partly because you don't have to maintain two changes but mostly that you can check what the documentation says by issuing a simple ' git grep -i <feature specific term>'. One might suggest that the developers will have to step up to the challenge "or similar" but the truth is that we are all humans and most of us have fast paced jobs where things like "updating the homepage git with corresponding changes" is very often down prioritized when services starts to burn and your customers gathers outside your office with torches and pitchforks.

So to conclude:

I'm totally in favor of reworking the tutorials but with the setup you are describing they will (IMO) only be truly valuable for googles opensource instances and for the few that also have something close to latest master deployed (which is virtually impossible for us that have limited staff resources and a commitment to 99.99% uptime).

Best regards

Sven

On Monday, October 30, 2017 at 7:07:26 PM UTC+1, David Shevitz wrote:

During the last user conference, I learned that many Gerrit maintainers and users would like improve the on-boarding experience.

To help with that effort, I'd like to create a Guides section on our website, www.gerritcodereview.com. The purpose of this section is to be a sort of documentation hub where users can learn about the Gerrit workflow, read tutorials for specific scenarios, and learn about best practices.

The reason I want to create a different site: I think it is important to have at least a subset of our documentation that is independent of the core Gerrit repo. First, this would allow us to more easily track analytic data so we can learn about what topics users are most interested in. Also, having content that is independent of a specific Gerrit release would allow us to get content updates to users at a faster rate.

I've already created a change to see what this section might look like. One thing that has been pointed out: we need to figure out how to handle previous versions of guides--perhaps by following a model similar to what we do for the product documentation. 

I'm interested in what the Gerrit community thinks--if you have a moment, please take a look at the change and let me know your thoughts.

Thanks!

--
--

To unsubscribe, email repo-disc...@googlegroups.com

[David Shevitz]

Thanks for such great and thoughtful feedback, Sven. You brought up a number of things that I had considered, but hadn't fully understood their impact.

Before I add some additional thoughts, I wanted to clarify one thing: I deliberately did not try to create a lot of "new" content for my Guides change. Instead, I was trying to provide useful content for this new section, but I did not want to invest too much time in case the change was rejected.

I definitely see your point: much of the Gerrit documentation must be tied to a release. At the very least, users need to know that topic X applies to version Y or later. I wonder if there are specific topics that might be version-independent; however, given the wide range of Gerrit versions that are in the wild, I don't know if such topics exist. This makes me wonder: where should we focus our documentation efforts? Typically, I've always focused on the most recent release. However, it may make sense to divide my time between documenting new features and updating older versions--especially if an older version happens to be the most popular or most used version of Gerrit. 

Here are some of the reasons why I was considering this new Guides section:

1. It seems like it is very confusing for users when they search for information on Google. As you pointed out, most users probably type a search query to locate the information they need. But given the number of open source projects using Gerrit, it's hit-or-miss what site a user will come across. For example, if you type "reviewing a change in gerrit" in Google, the first four results are from four different sites: openstack, gerrit-review.googlesource.com, Eclipse, and MediaWiki. In addition, each one of those results points to a different topic. One of the only ways I can think to work around this is to create an entirely new doc set that we can start to refer users to. I don't want to use the phrase "definitive doc set," but maybe that's the right phrase to use. :)
2. We need to improve the navigation and appearance of the doc set. Our current documentation platform is limited in terms of look and feel (CSS and such) and navigation. However, I don't want to request any engineering work needed to implement a new publishing platform until we can get some sense of what changes have the most positive impact on users.
3. I can often create content faster than our build process allows. It would be great if we can get that content out to users, instead of making them wait until someone updates their version of Gerrit.

Perhaps we could address these last two issues by creating a "beta" documentation site on www.gerritcodereview.com? That would allow me to make changes and share those changes to Gerrit users. Even better, if I come up with a new topic or layout that lands well with users, they could make the request for that change to make its way into whatever version of Gerrit they're using. (I don't know how feasible that is, but it's a thought.)

To address the first issue, I'm not sure what options are available other than to create a set of content that is, if not independent of a specific Gerrit version, at least lives outside of a Gerrit build. I'm very open to suggestions however.

Again, thanks for the feedback! I look forward to learning more.

Dave

--
--
To unsubscribe, email repo-discuss+unsubscribe@googlegroups.com

More info at http://groups.google.com/group/repo-discuss?hl=en

---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.

To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

Dave Shevitz

Technical Writer

[Sven Selberg]

Hi,

Together with some inline comments below.

Documentation deployed by each site

I could list a range of arguments as to why the documentation should be deployed with each Gerrit instance, but I have concluded that all of them are sentimental and therefore invalid.

The only issue I can think of (and that I believe we can ignore) is that there are public Gerrit instances and "company-internal" Gerrit instances. For public instances it shouldn't be that much of a problem to link to the one-public-documentation-to-rule-them-all and that would make life in the public domain a lot less confusing when looking for Gerrit documentation. But for company-internal instances the links to documentation would be external.

Suggestions

* The first step would be to reorganize the current documentation to get a better sense of what is version specific and what can be extracted into some sort of omnipotent truth.

* After that (or simultaneously), rewrite the parts of the documentation that needs improvement.

If you do these two steps first you postpone the fork that is inevitable when forking the documentation to start working on the "beta documentation site". And it will also be easier to converge them again afterwards if the structure is somewhat similar.

* IMO It would be a mistake to separate the entire documentation from the Gerrit versions (Gerrit stable branches). Which is to say you should be able to track version specific documentation. If the documentation lives in a separate repository the difference could be tracked by having them in correlating branches in that repo.

* There could be benefits to having at least the technical part of the documentation in the same repository as gerrit (REST API definition, project & system configuration sections, Access categories, Prolog facts ...) depending on how complicated the deployment setup would get.

BR

Sven

On Wednesday, November 1, 2017 at 8:10:21 PM UTC+1, David Shevitz wrote:

Thanks for such great and thoughtful feedback, Sven. You brought up a number of things that I had considered, but hadn't fully understood their impact.

Before I add some additional thoughts, I wanted to clarify one thing: I deliberately did not try to create a lot of "new" content for my Guides change. Instead, I was trying to provide useful content for this new section, but I did not want to invest too much time in case the change was rejected.

Agreed

I definitely see your point: much of the Gerrit documentation must be tied to a release. At the very least, users need to know that topic X applies to version Y or later. I wonder if there are specific topics that might be version-independent; however, given the wide range of Gerrit versions that are in the wild, I don't know if such topics exist.

As I eluded to, and Luca clarified, the philosophy behind, or if you will, the actual Workflow when working with Gerrit. Explanations at a higher abstraction layer with some "absolutes"  ( change-id's in the footer, changes, patchsets, submit-strategies (although these are a little more volatile)) would certainly make for a topic that would be more or less version agnostic. And I believe (as Luca) that such documentation would be very valuable since today you will have to traverse back and force between the different tutorials to piece together some sort of concept of the underlying principles.

This makes me wonder: where should we focus our documentation efforts? Typically, I've always focused on the most recent release. However, it may make sense to divide my time between documenting new features and updating older versions--especially if an older version happens to be the most popular or most used version of Gerrit. 

Personally I don't think there's much point in supporting this new documentation layout for older versions than latest. The difficulties with maintaining documentation that is valid for all "live versions" never the less becomes a reality once next version and the version after that is released.

I think that whatever we choose to do we should have (at least) parts of the documentation that are version specific and version controlled so that we can easily update documentation for one version without interfering with other versions (if that piece of documentation isn't valid for them) in the same way we handle the Gerrit source code. My objection was about having them on one branch in the homepage project.

Here are some of the reasons why I was considering this new Guides section:

1. It seems like it is very confusing for users when they search for information on Google. As you pointed out, most users probably type a search query to locate the information they need. But given the number of open source projects using Gerrit, it's hit-or-miss what site a user will come across. For example, if you type "reviewing a change in gerrit" in Google, the first four results are from four different sites: openstack, gerrit-review.googlesource.com, Eclipse, and MediaWiki. In addition, each one of those results points to a different topic. One of the only ways I can think to work around this is to create an entirely new doc set that we can start to refer users to. I don't want to use the phrase "definitive doc set," but maybe that's the right phrase to use. :)

IMO it's reasonable to have the documentation deployed on one, universal, site instead of on each, individual, instance.

1. We need to improve the navigation and appearance of the doc set. Our current documentation platform is limited in terms of look and feel (CSS and such) and navigation. However, I don't want to request any engineering work needed to implement a new publishing platform until we can get some sense of what changes have the most positive impact on users.
2. I can often create content faster than our build process allows. It would be great if we can get that content out to users, instead of making them wait until someone updates their version of Gerrit.

I believe that this is also true for all Gerrit developers fixing bugs and contributing features :)

--
--
To unsubscribe, email repo-discuss...@googlegroups.com

More info at http://groups.google.com/group/repo-discuss?hl=en

---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Dave Shevitz

Technical Writer