RFC-012: internal knowledge base #28
Conversation
ryanmacklin
requested review from
camerons,
flicstar,
bwklein,
acpkendo,
carriecrowe1138 and
barbaricyawps
|
Nice work here, Ryan! In general, I am strongly in favor of having some sort of internal documentation mechanism for the project. However, I'd possibly like to address some questions and concerns before giving final approval. Question 1: Content platform interactions I think the last time I was in a meeting where that was discussed, we talked about how our current website is trying to serve two groups at the same time: 1) community members and 2) future users who will use our product (templates and other documentation resources). The problem is that by trying to serve both audiences, we serve neither of them well. So there was some discussion about the possibility of creating two websites or two different sections of the main website that is focused on one audience vs. the other. Do you think the internal documentation should be contained on the website focused on new community members or should it be an additional content platform? Maybe it would also help to define a few general guidelines for when something goes in the internal docs vs. a different platform, such as its intended audience and purpose? Concern 1: Tech stack and cost If possible, I think we should make it a requirement to explore free, open source solutions to internal documentation since we don't really have funds to pay for a service. Is there an open source alternative to Confluence, for example? Something easy to use but lightweight to set up and maintain? Praise |
This also came up in the retros, so I wanted to tackle it—both as a tech issue, and as an issue of what should go/not go in the KB.
I wouldn't have internal docs be on the main site. If we're looking at trying to create a coherent "hey dev, you need help, here's what we can provide" experience on the site, then we shouldn't muck up our SEO with internal docs. That'll be especially true if we grow our userbase to the point where people Google for answers about our templates. We'd want them to only find help relevant to them, not a combined mess of internal and user support.
Absolutely! The quick version, which could use nuance, is: "Does this information apply to people outside of our contributors, namely our users?" If so, then it is (or is in part) something for the public site. If it's only relevant to our contributors, it should be in our internal KB.
I'd put this on the tech team, not content strategy, since this isn't user-facing. It could be as simple as "use what's in GitLab, with a specific setup." We shouldn't spend a lot of time on getting this spun up, as we can be flexible with a contributor-only knowledge repo. (And we can eff up and try something new, if our first implementation ends up being garbage.) If that doesn't work, then maybe something like a subdomain of "contributor.thegooddocsproject.dev" could host a simple Hugo site for this. But I'd like to keep the tech team work on new Hugo implementations to a minimum, so that bandwidth can stick to our user-facing site.
That to me sounds like an additional requirement (one that was already in my mind, but not explicitly stated) we should make sure is baked into analysis. |
|
One thing to add (per talking with Alyssa over VC): said internal KB is where we can put what's currently on the site that isn't user-oriented, like info on our working groups. By shifting all of that to a KB, we keep our SEO tight on our core site. (Aside from a "how to contribute" link to said KB on our site.) Which means we can, if we move forward with this, restructure our community-facing stuff on the site with intentionality that makes our SEO less muddled between people searching for us because they heard we can help them with docs, and people who hear about us and are interested in contributing. |
|
At our most recent Content Strategy catchup, @carriecrowe1138 presented a low-fi mock up of a site re-design which is totally in line with what is being discussed here - in terms of focussing our site on our "product". By default that means housing our project-based docs in a KB or similar. |
| - [ ] Draft the core info on how to use & contribute, so we're all on the same page about it | ||
| - [ ] Create the initial structure/document tree | ||
| - [ ] Ask group leads to dump critical or infrastructure knowledge from their brains or disparate notes into the KB | ||
|
|
There was a problem hiding this comment.
- Scrape the existing GitHub repos and wikis for any project and process information that is relevant to capture in the KB
- Comb existing Google drives per working group for relevant info to move into the KB
|
I'm all in on this @ryanmacklin 👍 You don't mention a team, or a lead. I suspect we'd need one (or both). |
|
This is definitely needed! Thanks, Ryan! I agree with Felicity that a static site in GitLab would be great. |
|
Pin that @barbaricyawps has critiques/concerns about using GitLab wiki |
|
I also discovered/realized that we can host 'internal' static sites on GitLab Pages that only project members can see when logged in to GitLab. https://docs.gitlab.com/ee/user/project/pages/pages_access_control.html Another viable option is to use the 'Group' level Wiki in GitLab. It has come a long way from earlier versions of this tool, but I must admit that I have not used it much. It seems to be a fairly simple Git-backed static site generator of its own, independent from any project repositories we might have. |
| * Isn't fragmented across different platforms or accounts | ||
| * Is easy for new contributors to access | ||
| * Has a sense of hierarchy | ||
| * Allows contributors to dump critical or needed info in a place that keeps them from being a bus number |
There was a problem hiding this comment.
| * Allows contributors to dump critical or needed info in a place that keeps them from being a bus number | |
| * Allows contributors to dump critical or needed info in a place that prevents them from becoming a bottleneck |
| * Allows contributors to dump critical or needed info in a place that keeps them from being a bus number | ||
| * Has some sense of discipline/oversight to keep it from becoming disorganized or discordant | ||
|
|
||
| This is internal-facing material, which is about the audience, and not about privacy. We should assume all information is publicly viewable, just intended to be viewed by those with working group context. Our template/product users wouldn't need to know this stuff, but there's no reason to hide it. |
There was a problem hiding this comment.
| This is internal-facing material, which is about the audience, and not about privacy. We should assume all information is publicly viewable, just intended to be viewed by those with working group context. Our template/product users wouldn't need to know this stuff, but there's no reason to hide it. | |
| This is internal-facing material, meant to be consumed by members of the Good Docs project. Our template/product users don't need to know this stuff, but there's no reason to hide it. Therefore, we keep all information viewable to the public. |
|
|
||
| ## Motivation | ||
|
|
||
| We don't have a good way to share information to use contributors, or a common places where information can live and grow. This was mentioned by multiple people during our recent retrospectives. |
There was a problem hiding this comment.
I agree to some extent.
I can share some experiences from what we did in the Chronologue project to try to preserve knowledge. Spoiler: We are still figuring out how we want to do this sustainably, so your RFC is more than welcome. :)
Approach 1:
Before I joined, I found a wiki in shambles and a running Google Doc with meeting notes.
I updated the wiki with our newest set of assumptions to stomp a fake product out of the ground.
For a while, that was a really good way to do it, as we were just a small group and didn't have as much velocity.
And then more people started coming along and needed to build context, learn how we work, essentially get onboarded.
I found myself explaining a lot of things verbally instead to pointing to the wiki (probably because I wanted to build social rapport).
Approach 2:
To create a more solid point of reference, I started creating a README page to give people an idea how to actually contribute.
As for the wiki, I decided to migrate some content that I deemed was solid enough into a more "permanent" format. For example, in one wiki entry, I explained how the Chronologue telescope works "scientifically". I turned that into a concept in our docs folder.
We try to do that with as much knowledge as we can, and plan on deprecating the wiki eventually for maintenance reasons. I think the wiki failed due to lack of ownership, whereas more permanent files require one or more authors to write something and ideally a PR. It requires more commitment, and therefore, I think the outcome is higher quality.
If that is the best way to do it, well, I don't know.
P.S. I wrote this comment before reading the rest. I am curious what you propose.
There was a problem hiding this comment.
Ideally, if we all know we have a core space, and are expected to use that space, those overall problems get resolved.
|
|
||
| We could use a GitLab wiki or repo as a place where contributors can post material or comment on said material with questions, corrections, etc. | ||
|
|
||
| We'd have some guideline on structure, intent, etc. Each core initiative would have a space for their information, along with general information, community resources, etc. |
There was a problem hiding this comment.
I think we need to find a good balance between keeping the information in a place where you would expect it/need it vs. keeping it somewhere where it is discoverable.
For example, I experienced that many of my Chronologue group members are pretty new to Github (let alone Gitlab), and switching/finding things in different places than their "home" repo is pretty hard for them.
|
|
||
| We'd have some guideline on structure, intent, etc. Each core initiative would have a space for their information, along with general information, community resources, etc. | ||
|
|
||
| Ideally, our docs would make use of our templates—in fact, they would make for great use/test cases. However, we would allow for a "quickly written" status, in cases where information needs to be dumped from someone's mind, but the time/effort cost in polishing isn't currently possible. |
|
|
||
| Ideally, our docs would make use of our templates—in fact, they would make for great use/test cases. However, we would allow for a "quickly written" status, in cases where information needs to be dumped from someone's mind, but the time/effort cost in polishing isn't currently possible. | ||
|
|
||
| We'd have a mechanism for checking the freshness of content, though we can defer the details of that until later. |
There was a problem hiding this comment.
Agree that we need this, along with owners of the file/ reviewers.
| ### GitLab wiki: a.k.a. Do we already have this? | ||
| There's a wiki in GitLab, and [Aaron has release weight information there](https://gitlab.com/tgdp/governance/-/wikis/Guide-to-assigning-weight-scores-to-issues-and-epics-%28release-planning%29). Should we just go with that? Does that make sense for us as a group of groups? | ||
|
|
||
| Is the wiki going to be oversaturated with other purposes? Would it be difficult to use search functionality when looking for KB articles, due to non-KB stuff in the wiki also populating the search results? |
There was a problem hiding this comment.
Can you elaborate on what you think could be saved in the wiki that would qualify as non-KB stuff? If we can pinpoint certain things, we can brainstorm with the CS group where those things should live.
There was a problem hiding this comment.
This is a general question regarding technological limitations. Ideally there should be only KB material in whatever CMS or repo we use, but if we're not able to accomplish that, how to do we handle such a situation?
|
|
||
| Said information though could become out of date without a contributor realizing it, due to the nature of knowledge bases and the bandwidth of contributors. | ||
|
|
||
| We also need to decide on the access control. Having new contributors being able to edit can be great for finding holes in the content, but could also be an issue if contributors put misunderstandings into our KB without others noticing right away. |
There was a problem hiding this comment.
I see this as a blessing and curse as well. Having a stricter format that needs a PR before contributing would prevent these things, I guess.
There was a problem hiding this comment.
That gets into drafting the core info on contributing to the KB, which is in the implementation list
| {This section is optional and is where you can list questions that won't be resolved by this RFC, including those raised in comments from community members.} | ||
|
|
||
|
|
||
| ## Decisions deferred |
There was a problem hiding this comment.
I feel like we should be in the clear about these two things before we settle on a wiki. Seems to important and I guess it is a pain to migrate later on.
There was a problem hiding this comment.
Added those to the implementation checklist
| We'd have a mechanism for checking the freshness of content, though we can defer the details of that until later. | ||
|
|
||
| ### GitLab wiki: a.k.a. Do we already have this? | ||
| There's a wiki in GitLab, and [Aaron has release weight information there](https://gitlab.com/tgdp/governance/-/wikis/Guide-to-assigning-weight-scores-to-issues-and-epics-%28release-planning%29). Should we just go with that? Does that make sense for us as a group of groups? |
There was a problem hiding this comment.
In my mind the (a) wiki is the place for this type of information, as it's basically what they were designed for. The tricky part will be where it resides, and slightly related, if there's one for everything or one for each WG (as each repo has its own wiki I believe). I usually favor the "source of truth" approach, which implies we have one wiki to rule them all. Of course, at this point the IA and content strategy becomes super important...
There was a problem hiding this comment.
+1 to all @barbaricyawps's first list of concerns/praise.
- My experience with wikis is they are great at the start, but then become unmanageable later, because future maintainers are scared to remove old messy content. Or some enthusiastic volunteer comes in and "cleans up" old content and makes a mess. (Same problem as with any content, just amplified.)
- This can be mitigated if an owner provides a level of oversight to what is contributed, continually pruning and directing new contributors.
Suggestion (non-bloking): Establish an owner role for the knowledge base and ensure it has a volunteer before approving this RFC.
I have hesitations about this RFC as worded, but it is "near enough", is "fixable" later if needed, and I have a high level of confidence in the people supporting this so far.
I'm not likely to have bandwidth to do a second review, so will approve now.
|
+1 from me. I would love to put my hand up to be knowledge base owner, if that becomes a thing. |
Note to RFC reviewers
This pull request description is not the actual RFC. To view the actual RFC, click Files changed in the top menu for this pull request.
NOTE: We recommend reading the files in their rendered format rather than their raw format.
Current RFC status