Monthly Product Update in Intranet

[gianfranco-l]

Status quo

• Team monthly Product update written in Slackbot and sent out to news-product.

Proposal

• Monthly Product update written down in the Intranet + TL;DR and link to the relevant Intranet page sent out via Slackbot to news-product;
• Where in Intranet? Current suggestion: subsection under Product;
• Structure:
  • 1 specific page per update;
  • TBD: 1 section per team / 1 section per month / other ?

cc @giantswarm/sig-product @giantswarm/product-owners

[marians]

@gianfranco-l Let me knoe if you want assistance with creating some example content.

BTW I don't think we have to copy the entire history from Slack into the intranet. An example set of a few pages should do.

[gianfranco-l]

@marians right, the rationale is to document from the moment we use the new proposal, not the past :) regarding the structure of this new section,this is yet to be defined AFAIK :) we'd need some direction here from the team that owns the intranet (if exists :) )

[puja108]

To keep it simple, I'd say we just start with Product / Updates / TeamName as folders and then each update is a page/.md with format YYYY-MM.md this way the autosorting should also work.

We can iterate on the structure if we see people having issues with it.

Content structure I'd also start with keeping what we have and just adding a TLDR at the top. @marians helping out with some nice examples might be cool.

[gawertm]

@puja108 I was jsut thinking if we divide by team, one would have to click through each team to see the latest updates. not sure how convenient this will be. but I also do not have a better approach in mind. maybe 1 .md per month with all the teams updates?

[puja108]

Right the alternative would then be going with Product / Updates and then YYYY-MM-teamname.md, could still work well.

[marians]

+1 for a flatter structure. Should be doable.

[marians]

Some general content questions.

Currently geekbot asks for past and future.

• What did your team achieve last month?
• What will you do this month?

Do we want to keep it this way?

Since the updates are usually not written at the end/beginniong of a month, the understanding of "last month" and "this month" is a bit fluent, I guess. Do we see it as something like a moving 30 days window?

The reason I'm asking is that it's simple and clean two use headlines like Team X – October 2022, but if the post covers a bit of September and a bit of October, this headline format makes little sense.

[marians]

Intranet proposal

Using the blog layout provided by docsy.

/docs/product/bulletin/

/docs/product/bulletin/2022-11-08-atlas/

/docs/product/bulletin/2022-11-15-rocket/

[marians]

To check it out live, please use https://github.com/giantswarm/giantswarm/pull/24673

[gawertm]

@marians @puja108 I was even thinking about an even more flat structure like 1 .md file per months with all the teams in it. Or would it get too big? and I also think we should stick roughly to a calendar months e.g. product update october, november, etc.. I agree that a moving 30 days window would be too hard to handle

[marians]

In SIG Product sync I just got the feedback that the part about plans is a duplication if what POs tend to cover in the public roadmap issues. So I'll remove that from the draft.

I will also work towards supporting full content display on the list page. (The requirement of having a distinct URL for each news posting has been mentioned, so there will still be a details link for each one.)

[gawertm]

hi, we were running out of time in the meeting, but I actually disagree little with what @alex-dabija was saying about the plan being a duplicate to the roadmap. I think in the monthly product updates you would summarize it in a different way. Also you would include private things, collaboration topics, etc. that are not in the public roadmap. also we may work on things in the next 4 weeks that are only ready in a few months. So the roadmap category "ready soon <4 weeks" doesnt mean its all the team works on in the next 4 weeks

no hard feelings though if we remove it - I can see that there is certain overlap

[marians]

Latest preview

Here is now a proposal where all content is shown on the index page. Also the Acknowledgement vs. Plans distinction is removed from the example content.

As I changed the single page template to be the same as for all other intranet pages, the Prev/Next navigation does not appear on the details page for a single post. However there will be pagination for the index page.

/docs/product/bulletin/

/docs/product/bulletin/2022-11-15-rocket/

/docs/product/bulletin/2022-11-08-atlas/

[marians]

The above is now merged. Next steps:

• Somebody must mute/adapt the geekbot prompts. @puja108 ?
• We have to establish the practice of posting once per month and also sharing the content in #news-product.
• Do we need a bit of documentation for this? See text below.

---

How to publish a monthly product bulletin for your team

1. In the giantswarm/giantswarm repository, navigate to the content/docs/product/bulletin folder.
2. Copy the top part (front matter) of file 2022-11-03-honey-badger.md
3. Create a new file YYYY-MM-DD-TEAM.md where YYYY-MM-DD is the current date and TEAM is your team name (in lowercase letters).
4. Paste the copied front matter into the new file. Make sure to have --- before and after the front matter. Adapt it like this:
   • date: Current date in form "YYYY-MM-DD".
   • title: "Team TEAM_NAME MONTH YYYY" where TEAM_NAME is the team name, MONTH is the Month, and again YYYY-MM-DD is the current date.
   • toc_hide: true to avoid having every bulletin appear in the left-hand menu.
   • author: Your name.
5. Add your news content in Markdown format below the front matter.
6. Commit your changes to a new branch, push, create a pull request, get approval, and merge the PR.

[gawertm]

can we have this instruction in intranet also?

[marians]

@gawertm Sure. I just don't find a good place where to put it. Any idea?

[gawertm]

I also dont know. nothing really fits. maybe just under the bulletin? How to monthly product update. or in the documentation section..

[marians]

The howto is now placed in the intranet, under Product / Bulletin.

@gianfranco-l @puja108 Do you want to keep the issue around, or close it?

[puja108]

Sorry, only now catching up on this. I'll communicate and adapt the geekbot

[puja108]

I adapted geekbot with a reminder to do the PR and then the question just asks you to post your TLDR with a link.

On that note, I also added in the reminder that we want a TLDR that is posted to Slack (but also included in the MD) as we discussed early on.

Also, rethinking our discussion on Roadmap being the plans for next months, we do indeed sometimes have internal and customer related updates that would be good to keep internal as @gawertm mentioned. @giantswarm/product-owners WDYT, I'd say esepcailly for now until we get the Roadmap board in order to actually be able to serve as a source of truth, let's keep the updates. We can re-evaluate once the Roadmap board is regularly used and maintained and we see people actually using it. I worry not just about having the information, but also about communication of said information, clickthroughrates from Slack might actually be quite low and some of that information is quite important.

[puja108]

Alternatively, the plans that are not in Roadmap or important to mention could just live in the TLDR, which is then also posted to Slack. This way the SoT would stay, but it would be better digestable.

[gianfranco-l]

I am very confused because the intended objective of this proposal was to have a single source of truth of product team updates, the end result seems to have 4 places (TLDR in slack, bulletin in intranet, roadmap board and availability overview) were to share some part of info or duplicate one. Besides being unclear where to put which information for whom and why, I think the end result would lead more confusion to stakeholders and more effort on teams rather than make everything easier and information flow clearer for everyone

[marians]

I agree with Gianfranco in that it's getting more complicated. I suggest to skip the demand to posting a duplication of the bulletin to Slack. (If people want to post and duplicate, I also would not stop them. But it has to be clear that there is an intranet URL for this sort of info.)

Regarding future plans per team: Does it get simpler if we say "Only mention items that are not covered by the Roadmap"?

[gianfranco-l]

to better refine my statement here, it would actually be 6 places: the aforementioned 4 + the roadmap Miro board + changelog of sales availability overview.

[gawertm]

so what are you suggesting?

[gianfranco-l]

at large and as a whole, I think we need to redefine which are our communication objectives as Product (what to communicate, to whom and to enable them to do what) and then start to fragment them in smaller outcomes that should help us to better find the key initiatives to work on and how (if we do a bit of something all over the place with no coherent vision and purpose, we end up in the situation we are in, 6 deliverables, what is public and what is not being unclear, quite some effort from teams, external stakeholders not happy)

for the specific product bulletin case, what Marian already suggested, basically not overcomplicate: let's do the Product bulletin documented in intranet and TLDR in Slack. Current Product updates in Slack are meant to be for internal use only, when we will open the intranet we'll still have some private intranet doc anyway and Product bulletin could just be part of it.

[puja108]

To clarify, the roadmap board, availability overview and roadmap miro (incl changelog) are not things that have been added with this change. They were iterations that were made within SIG product over the last few months. As mentioned this monday in SIG product I agree that some aggregation can and should be done to reduce the organizational effort for POs. Horizon will work on some improvements (e.g. status syncing between team and roadmap board) here and we believe that the roadmap board can be an essential tool for communication for us also internally, with which we can get rid of some other boards (e.g. sig product board) an communication tools. I believe that it can replace the current miro with the availability overview and the simplified roadmap in miro, but for that we need to put some work into actually using it. In it's current form it is not a good replacement for the info we have abstracted elsewhere.

I can get on board with the idea though to take a step back in the coming year and refocus on the problems we are trying to solve on the communication side and find fitting solutions for them.

For now I'd close this issue, and refer to Horizon issues regarding roadmap board iterations.