Review Requested: byos-overview

[jduckles]

📄 Source | 🌐 Rendered

👤 Assigned to Nathan for review.

[nkinkade]

@jduckles: The byos-overview KB document seems to be a highly pared down version of the official documentation on the website:

https://www.measurementlab.net/contribute/host-managed/

It feels like not a great idea to have duplicate documentation, which just introduces the challenge of keeping them in sync as things change over time. What value is this particular KB article bringing that isn't already covered by the existing documentation?

[nkinkade]

Following up on this, @newcombms informed me that this KB is going to be the new canonical location for all documentation, how-tos, and FAQs. This implies that the existing BYOS documention is not going to be published on the new website. With that in mind, then the current byos-overview article is way to thin to be even close to a replacement for the existing documentation. In other words the document shouldn't be an "overview", but instead the complete documentation. It would make sense to me to basically take the entirety of the existing "host-managed" documentation and past it into this new KB article. What do you think?

[newcombms]

@nkinkade there is a host managed documentation page currently tee'd up for the new website, but we can move it into the KB. I believe the idea is we will do this in phases, so we can keep current documentation and move it slowly into KB after website launch. @sermpezis lmk if that is how you envision it.

Perhaps it would be helpful if you could make a list of documentation that we need to ensure is included in KB @nkinkade ?

[nkinkade]

Personally, I think the KB is not the right place for formal documentation, and regular pages on the site are a better fit and come across as more professional, for lack of a better word. To me, a "knowledge base" is best suited for short tips, tricks, hacks, troubleshooting, etc. Notwithstanding my personal opinions about what a KB should be, I don't think we should be dual publishing anything for virtually any amount of time. With this issue as a point in case, it's hard for me to imagine how this byos-overview is useful to anyone, since all it does is highly summarize the existing, well-thought-out full documentation. And the full documentation is already broken into logical sections and is easy for almost anyone to parse. It also requires that any change to one necessitates an update to the other, and we don't want to find ourselves in the situation of having to keep two separate documents in sync.

[sermpezis]

I think @nkinkade 's point about the actual usefulness of this high level summary is valid.
@newcombms that's how I was thinking about documentation and KB: to move the documentation there. (and tagging "official documentation" articles in the KB with a specific tag, we could in that way to differentiate them from other types of articles, such as short tips, etc., so that they are more professional - based on @nkinkade 's comment)

Having said these, @jduckles can you (i) move the detailed BYOS documentation under this article, (ii) create this "official documentation" tag (if you think it's a good idea, or suggest an alternative), and (iii) when done ask again @nkinkade for review?

[jduckles]

From the discussion above, I see a clear divide:

• if it's instructional (steps, commands, how-tos) it belongs in the KB.
• if it's broadly explanatory (what something is, why it matters, whether it's right for you) it belongs on a website page.

To address the duplication concern, the full content of the host-managed-server page is now formatted and brought into the KB template here: https://github.com/m-lab/knowledgebase/blob/main/src/content/articles/byos-overview.md. All content from that page is now formatted with tables, selective bolding and rearrangement. @nkinkade it would be great to get your review on that when you have a moment.

We're in a transition between old and new website and the choices we make now should reflect the future state we want for someone arriving at the site, not just preserve the current one. I don't think a special tag adds value for the reader.

As a next step, I'd suggest paring down the https://mlab.draftlab.dev/byos/ page and linking out to the KB article for anyone who wants the tangible steps to get started.

[nkinkade]

@jduckles: Thanks for this update. I completely agree with the divide you outlined above. Quick clarification: is that divide just what you observe from the previous discussions from others, or is it a divide that you personally see fit for the KB?

Regarding the updated byos-overview document, it all looks accurate to me on first pass, but I do notice that it still just summarizes the existing host-managed document. That is, it may summarize a whole paragraph in just one short sentence, and it may entirely eliminate explanatory text in other cases. This may be intentional, or it may be AI trying to make the document as terse as possible while still giving voice to the high points. I intentionally was fairly verbose in the original document to try to completely communicate what the site host can expect.

My personal view is that the old document is fine the way it is, but that is to be expected since I'm the one who wrote it. With that in mind, I'll say that the current byos-overview document is a fair summary of the original document. Whether a summary is sufficient and desired as the canonical BYOS documentation offered up by M-Lab, I'll leave that for @sermpezis and @newcombms to decide, since it may be that I'm overly verbose and a more broken up, terse summary is actually better for the typical BYOS host than what I wrote.

[jduckles]

Nathan, it is a divide that I see @newcombms seeking so that the prose on the website is manageable at a less technical level and the knowledgebase content can be the domain of more deeply technical / code content. While the KB and the website are one-and-the-same now, I think it is useful for the team to think about the new kb area of the website being where this deeply technical content can grow and expand in a structured way.

[newcombms]

@jduckles thank you I like the organizing principles you listed out and it aligns with what I had in mind.
@nkinkade following that info organization logic, if a document is for technical instruction and is living in the KB/GitHub, I don't have any editorial preferences - I want those documents to accurately reflect whatever the technical team wants to communicate.
So I defer to @nkinkade and @sermpezis for which version of the article/what information should be included.

[nkinkade]

Many of the tables of the current byos-overview document are a nice addition to the documentation, and make some of the content standout better, so that is a definite inprovement. However, my opinion is that the current host-managed documentation should be ported over more or less word for word, possibly keeping many of the tables. The existing documentation is already in Markdown format, so there shouldn't be much to do:

https://github.com/m-lab/website/blob/main/_pages/host-managed-documentation.md

Regarding this PR as it sits now, it is a pretty good summary and simplification of the existing documentation, and in that sense it look good to me. I'll defer to @sermpezis for the final call on whether this summary is what we want for the official BYOS documentation, or whether we should more or less port over the existing document.