Documentation & wiki

Hmmm … @swalladge I like the idea of making documentation more light-weight. The existing set of private docs are are already in markdown. Plus GitLab has its WebIDE so they can be edited from the web browser. Thats almost a wiki. Maybe having a subfolder with less stringent rules on approvals would be enough? Also the whole lot could be prettified if we wrapped them in GitLab Pages. That would give you a wiki that also allows for MRs and discussions?

There is still the potential for that to devolve into a hard to maintain pile “pile”. GitLab has shied away from using a wiki for its handbook (https://about.gitlab.com/handbook/handbook-usage/#wiki-handbooks-dont-scale).

@swalladge @kahlil A git repo of markdown files is already a wiki - with the gitlab GUI it’s as simple to edit as any wiki, but with the added option of being able to be able to use a PR for reviews. Documentation is like code, it should be reviewed. And for cases where the change is truly trivial, we already have a clause allowing to merge a PR without a formal review. Adding a wiki would just add another different place to store documentation, and introduce ambiguity as to where things should go.

1 Like

I’m in agreement with the sentiment. But @swalladge still has a very good point: reducing friction is a big deal if you want more docs. IMHO, unreviewed documentation is better than no documentation. an unreviewed piece of documentation is better than if it didn’t exist at all.

It is probably the reason that Wikipedia is so successful and so useful (even if not 100% accurate): changes (and reversions) are easy to make, reviews are done afterwards, and discussions are tied to the topic and kept in the same place.

I have seen plenty of Google Docs being used internally kinda like a wiki, but I’m not particularly fond of the way they work for all usecases (comments are kinda ick). I’ve also seen Discourse be used as a wiki, but I don’t buy it. A lot of info ends up in the thread, as opposed to neatly organized in the top post.

I have also seen Gitlab MRs used as wikis. I myself refer to some of my pull requests when somebody asks how to test something. But the search engine kinda sucks, unfortunately - plus, MRs aren’t categorized, which would also help.

Which is to say: a +1 for a separate place to store less formal, more fluid, easily findable, and easily changeable documentation.

5 Likes

Try to replace “documentation” with “code” in that sentence, and I think you will see how I approach this. How would you react if someone said “reducing friction is a big deal if you want more code. IMHO, an unreviewed piece of code is better than if it didn’t exist at all.”

It is true in some sense, but only if that piece of code/documentation is only a prototype, and gets fleshed out properly, gets tests and is reviewed before it’s actually relied on. Adding a wiki just gives an excuse to not finish the job. If we want more documentation, we need to allocate more time to write it, not lower the standards.

1 Like

We already have the handbook, the onboarding courses, the documentation repo, this forum (which supports wiki posts), Mattermost, Google Docs, and probably others. I’m open to improving how we use and maintain our documentation, but I really don’t want to add any more tools into the mix.

2 Likes

@antoviaque, @braden, I understand and agree. But bear with me one last time: I’ll give a real example, you tell me how you think I should handle it, and however you think is best, I’ll do it and shut up. :wink:

Consider this PR to Ocim. It adds a separate text file with suggested instructions on how to run Ocim on an (LXD-managed) LXC container. Putting it lightly, it was not met with universal approval, for good reason: we don’t want to support a deployment method that only a fraction of users, or even developers, would ever want.[1]

Nevertheless, what should I do with it? It is likely to be useful to someone, even if it’s just myself after an OS reinstallation. But it has evidently not passed a formal review. It can live in this branch forever, such as a reported branch that adds some level of Docker support. But that’s just it: nobody’s likely to find the branch ever again, much like I never found the Docker one.

Aaaand done. :slight_smile:

[1] While LXC for app containers has lost the battle with Docker, for system containers it is still awesome. Which is to say, if you want to run something in a container and there’s no Docker image, Snap, Flatpak or otherwise for it - say, Ocim, or even Zoom - LXC is one way to go about it. (Yes, you can run X apps in LXC containers).

@adolfo I think that’s actually a good example of reviews for documentation working well. In this case, just like with a wiki, your documentation exists, and if someone wants to setup Ocim on a LXC container, they can build upon the work you have done there. It’s just a matter of clicking “edit” on your branch/PR on github. But unlike what would have happened with a wiki, here the work has been reviewed, and there had to be a decision about whether we would want to support this documentation on the long term. This is the part that has been pointed out as an issue during the review - while the documentation in itself is good today, the cost of ensuring that this would be kept up to date on the long term would be too high. It stings to get a PR refused upstream, but the decision to not merge it allows to differentiate formally between documentation we commit to maintain, and a page for which we don’t take on that commitment.

Now, just like with any decision to accept or refuse to merge a PR during an upstream review, it doesn’t prevent you from still maintaining that documentation, if it’s useful to you and/or others. It can still exist on a different branch or repo. The branch is publicly available, you could still find the PR, and it’s discoverable, even without being given a direct link. But there is a formal distinction with the official documentation of Ocim - a newcomer couldn’t end up confusing it for one of the supported methods.

1 Like

@adolfo Btw, to help with discoverability, you could always add a link to your branch from the official repo? This way someone looking for it could still find a reference in the official documentation, but the difference would still be clear, especially if the link is accompanied wiith a mention that it’s unsupported and might be out of date.

@swalladge, @adolfo, @antoviaque, @braden

A lot of different things being discussed here: lack of docs, reducing friction, maintaining quality, uncertainty of utility, ensuring discoverability, maintenance. Some of these deserve a thread of there own.

A simple alternative to the above branching model would be a dedicated folder/namespace under the private docs for individual users to store unofficial documentation, say:

    .../private/unofficial/{swalldage,adolfo,tartansandal,...}

With this set up:

  • no need for any new infrastructure
  • obvious that the content is unofficial
  • obvious who is taking responsibility for the content
  • easily discoverable by search
  • easily discoverable by browsing
  • no extra effort required to make discoverable
  • low-friction since markdown files under gitlab are wiki already
  • low-friction since they would not require formal review
  • can be easily referred to from mattermost or forum
  • can be updated/improved unlike mattermost and forum posts
  • easy to identify unmaintained unofficial docs (e.g. from prior staff)
  • less urgency to deal with old docs since they are unofficial

Most importantly, this content could be upgraded to official documentation (via a PR with review) once they have matured and if they have been shown to be more generally useful.

2 Likes

I think we veered off topic a long time ago, but I should add that just like code documentation should also be maintained. Each time some documentation is “tested” when someone uses it, they should also create a ticket in the documentation epic (BB-681) if they find that the documentation is unclear/inaccurate/outdated etc.

For what it’s worth, I’m perfectly fine with this PR being rejected. My point in this case is that a wiki would make a good home for such potentially outdated documentation, as it would be more easily discoverable.

In any case, I experimented with searching the forum, and it works well. For instance, I was able to find Loic’s similar attempt at contributing a Docker devstack to Ocim by searching for “ocim docker”. This is the main thing I’d look for in a wiki. So I’ll just create a wiki post in Tips & Tricks. Good enough for me. :+1:

1 Like

Just moved the current discussion about the wiki & documentation to a separate thread, to keep the original thread on topic.

I’ve brought up the idea of adding a wiki before - I really like the idea of a less structured, less controlled, lower friction method for documenting things. Maybe we need to seriously look into a wiki?

Advantages of a wiki, to complement what we have already, I can see are:

  • lower friction to adding things == more likelyhood that docs, tips and tricks, etc. can be added
  • a place to dump less structured docs, such as notes, tips and tricks (like we’ve been putting on the forum), links to mattermost discussions where we fixed things
    • yes we already have mattermost and the forum, but these are bad for discoverability
  • a place to link to interesting/useful reference jira tickets. We have a massive amount of useful information in jira tickets, but they are useless unless you know exactly which ticket you’re looking for because search is terrible. For example, we could have a wiki page on Mongodb, which would link to tickets where we have done mongo upgrades, gotchas, example command line snippets for common tasks, etc.
  • a place to structure information shared over mattermost (eg. copied snippets of conversations where something was broken and a working fix was found, etc.)
    • newcomers always have similar questions about the devstack, so wiki pages relating to fixing common devstack issues would quickly become a useful FAQ for newcomers.
  • heaps of other things?

A wiki in my mind would strictly complement our existing docs, and replace existing docs for anything that didn’t need to go through a review process. For example, our manual instance test checklist, official email templates, etc. would stay in a git repo where any changes must have a linked ticket and review process. But, things like general howtos, tips and tricks, example gmail filters, etc. can be moved to a wiki.

I have a lot of private notes about my workflows, little tricks, snippets, etc. that I would happily share if there was a simple way to share them where they wouldn’t just get lost in mattermost scrollback or forum posts.

Ok, sorry this turned into a longer post then I thought. New forum thread to discuss?

2 Likes

Just to keep the conversation going: I think the most important aspect to improve is discoverability of docs. We actually do have a lot of high quality, useful docs, but it’s difficult to know where to search (handbook, private docs repo, google drive, forum, particular tickets, other repos, etc.).

For example, there was one ticket about setting up certificates that @nizar had to do a lot of research to write up docs for the client, simply because he didn’t realize we already had a doc that covers this hidden in the shared google drive. (hehe this actually turned out well because we were able to improve the existing doc with new things he discovered, but still) I’ve also had similar experiences where others have been able to pinpoint tickets or docs that contained useful docs/tutorials/howtos/information that I wouldn’t have been able to find otherwise.

I don’t know how to solve this without duplicating information, or adding yet another platform to maintain though.

I would love some kind of good unified search engine which would cover everywhere where we have docs. I already have set up something like this locally that covers the handbook, private docs, and jira tickets, but I can’t really expand it much further. It’s also something that only benefits me with my workflow (I can share if anyone is interested, but it’s a pile of scripts heavily tailored for me …). Or some other idea/process/structure/software that allows pulling together our existing docs and presenting it in a way that improves discoverability.

CC @braden (Xavier suggested I ping you as docs overseer (I think this was the title?))

1 Like

@swalladge I agree, and I actually recently created a ticket for myself to think about that and propose some solutions in the new year - https://tasks.opencraft.com/browse/MNG-1817

One of the things I was thinking of was a website that shows the internal/private and public/handbook docs together, so that we can see them all at once and the search feature would cover both. But perhaps we can go one step further and just run ElasticSearch with some API integrations so that we can go to search.opencraft.com and search through the docs, Jira, Mattermost, mailing list, etc.

I’ll think about this over the holidays. If anyone has other thoughts, please share :slight_smile:

4 Likes

on the topic of discoverability, My long-standing approach is based on the assumption that “people will be using google anyway”, implying to me that “getting as much that can be answered directly in google is good”. Often I feel that looks like making sure api docs are public which seems to already be a strength here :slight_smile:

For things that are rather sensitive: so long as the “question being asked” is not sensitive, it might suffice to use a public Q&A site that encourages SEO, such that the questions are public, but the answers are private links to protected resources as appropriate.

+1 for improving discoverability. As a current newcomer, I can attest to the fact that it seems like most things at OC are pretty well documented…somewhere…but finding them can be a big challenge in and of itself, even once you know generally where to start looking. I like @braden’s idea of a central, all-encompasing, multi-platform search feature.

Following up on this thread - I have created a discovery doc about improving documentation discoverability. It’s still a work in progress, and I still have research to do, but since there are lots of strong opinions on the team about this topic, I’d like to get input early.

Please comment directly in the doc for any feedback or ideas related to discoverability and maintainability/organization, or comment in this thread if you want to discuss other aspects of documentation or unrelated ideas.

4 Likes

@team Just a quick reminder that I have a discovery about improving our documentation ^ and I’d like your feedback, if it’s a topic you’re interested in. I’ve only heard from a few people so far.

@braden, I have every intention of reading/commenting, but just haven’t found the time, yet. I’ll try to get to it this week.
https://forum.opencraft.com/t/documentation-wiki/589
forum.opencraft.com
CC-MAIN-2023-14
74349
application/http; msgtype=response
sha1:ZA4A7FRWK6PIOBTVNKV7YFMS6B6BBKMJ
<urn:uuid:0a03f5e1-1d4f-4226-ae27-ae88a881b031>
2023-03-29T00:31:21Z
161.35.245.1
text/html
sha1:ZH65YSFX3M5TSV42RWQ3VR33EBC3UTSR
<urn:uuid:5f026781-c5e1-415f-89d8-298618928257>
https://forum.opencraft.com/t/documentation-wiki/589
response
<urn:uuid:9c08f9bd-5ac4-4256-a989-4d414d7e4d55>
isPartOf: CC-MAIN-2023-14
publisher: Common Crawl
description: Wide crawl of the web for March/April 2023
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-67-67-36
software: Apache Nutch 1.19 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 1.4-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: https://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/