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.
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.
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.
@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.
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.
[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.
@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.
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:
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.
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.
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?
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?))
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
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
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.
