27

How do you manage your "internal team wiki" or company guidelines?

2 years ago from , Designer

Anything from file naming conventions to sketch file best practices, how does your team document and share these sorts of things?

I'm not talking about "handbooks" or culture-based content. The one example that immediately comes to mind is:

I'm currently using a gitlab wiki which works decently enough. I'm just wondering if there are better options out there.

20 comments

  • Jason Spidle, 2 years ago

    There are quite a lot of beautiful looking options for this, including Slite, Tettra, Slab, and Nuclino. Beyond those purpose-built tools, I could easily see one using Notion or Dropbox Paper.

    I tried to push our team to adopting one of these platforms but in most cases, the price was simply too high (though Nuclino does have a pretty generous free tier). Price aside, no one wanted to have yet another login and that's ultimately the thing. For the wiki to be regularly referenced, edited, and updated, it must be super accessible. The more people see it and the easier it is to make changes, the more likely it will actually become a useful resource instead of just a dormant repository of how your company operated three years ago.

    We ended up just using a Bitbucket wiki since we already pay for it and everyone has access. The initial launch of an internal wiki can be a little tricky so one thing that I did to increase engagement was to create a fun section called Lore for people to contribute stories about inside jokes. I think that kind of engagement has snowballed and now people are pretty quick to add things to relevant wiki pages when they can or to reference the wiki when they have questions.

    Another key to wiki adoption is having a wiki evangelist. There's got to be one person (and it sounds like that would be you) who is the driving force behind initial documentation and efforts to keep things organized. Here's a screenshot of the front page of our wiki, if you're curious. And here's an example of a lore entry to give you some ideas there. There's all kinds of crazy things in there.

    13 points
    • Andrew CiobanasiuAndrew Ciobanasiu, 2 years ago

      Ah. This is great! Thanks for your input. I went down the rabbit hole and found a very similar set of links. The lore idea is awesome. Definitely going to poach that for our own team (if you don't mind). A backlog of our favorite youtube clips is much needed.

      0 points
    • Andrew CiobanasiuAndrew Ciobanasiu, 2 years ago

      DN conveniently cut out the rest of my comment. Delightful.

      Was going to add that I just found a neat little thing called Outline: https://github.com/outline/outline

      Looks interesting. Especially since they have SSO via Google or Slack and you can serve it up yourself. Time to bother my devs, hah.

      5 points
      • Jason Spidle, 2 years ago

        Nice! Outline looks really slick and it is definitely handy that you can sign in via Google and Slack. The ability to search for articles straight from Slack is rad. Definitely something I wish we had. I couldn't figure out how much the hosted version cost though, any ideas?

        In any case, we had used Wiki.js for a time but left it behind when we decided to move away from maintaining hosted software for our own operations (we're an agency, so too busy with client work to keep our own stuff patched and up-to-date).

        Good luck with the devs. I hear they like React so maybe that'll help you sell it to them.

        1 point
    • Laure Albouy, 2 years ago

      Thanks for mentioning Slite :) — and your feedback on wiki pricing + adoption is super interesting! I love the Lore anecdote, definitely sharing that with the Slite team!!

      0 points
      • Jason Spidle, almost 2 years ago

        Slite was definitely my preference but couldn't convince the bosses. Love the design and the flow. Maybe someday :)

        0 points
    • Anastasia Churazova, 2 years ago

      Thanks for sharing your experience and mentioning Nuclino! If you ever want to give us another try, we'd love to have you ;) Getting your team on board can indeed be tricky, nice idea with the Lore!

      1 point
  • Anneliese HAnneliese H, 2 years ago

    We're currently exploring options for where our employee handbook can live (all things onboarding). We're thinking of factors such as accessibility and collaborative editing so that anyone can potentially contribute. We're also thinking of the potential for it to also house process documentation. Any other considerations we should take into account?

    So far I've liked the sound of Nuclino (lightweight, user friendly), but Confluence has also been another option to look into - though my assumption is that Confluence would make for a better place for technical documentation to live, plus it helps if other Atlassian products are being used. Thoughts on this?

    4 points
  • victor darrasvictor darras, 2 years ago

    With my team (development team, not much designers), we have a dedicated projet on Gitlab with all our documentations in markdown parsed by Gitbook when updated and served as a gitlab page.

    It also allow us to have much specific docs in project repositories, with the same workflow. It's easy to keep the doc up-to-date with the project and allow a vast majority of us to work with their daily tools.

    2 points
  • Leo E, 2 years ago

    Take a look at Confluence by Atlassian. We have tried so many wikis and anything free that’s off the shelf slowly degrades with time as users take short cuts. They’ve done a lot of subtle things to slow that degradation, while providing valuable modules. This is an all or nothing decision though. You will need to migrate all of your workflow to this to maximize impact and potential for success.

    Good luck!!

    2 points
    • Anneliese HAnneliese H, 2 years ago

      This is an all or nothing decision though. You will need to migrate all of your workflow to this to maximize impact and potential for success.

      Curious to know, what's your team's use case for using Confluence? Would you say that you use it mainly for technical documentation/knowledge sharing, or do you also use it for non-product related docs like HR/Admin/Ops?

      0 points
  • Dan Leahy, 2 years ago

    I'd be interested to know what other teams do as well.

    Heck, if I had to guess, most probably don't do anything at all (i.e. each designer runs independent and keeps tracks of their own best practice and tips/tricks). They share with team only when mentoring or providing advice or critique...

    2 points
  • Aaron Wears Many HatsAaron Wears Many Hats, 2 years ago

    GitLab on a self-hosted server. I can control access completely, and my documentation isn't potentially going to leak across a multi-user platform due to some dumb exploit.

    I don't see any need to complicate the workflow by having additional services to control what already works well :)

    1 point
  • Stefka IvanovaStefka Ivanova, 2 years ago

    Our company runs fully using G Suite apps, so we have the Happeo service. It's more of a "digital workplace" as we use it not only to collaborate within my team but also push announcements and brand updates company-wide as it also has good content/data management features

    "Pages" is where we keep everything organized and post our updates and keep our brand guidelines book. It's quite easy to use as you have quite range of customization - from layout to branding.

    You can check it out here: www.happeo.com. I'm happy to even share some screenshots if you're interested.

    1 point
  • Artur Eldib, 2 years ago

    Notion

    1 point
  • GOOD LUCKGOOD LUCK, 2 years ago

    We switched from "crappy" Atlassian ecosystem (wiki, Jira etc.) to Notion App (for wiki), and it's fantastic.

    1 point
  • Ryan RushingRyan Rushing, 2 years ago

    For now we use a Google site in Gsuite. That tool has really come a long way.

    1 point
  • Mattan IngramMattan Ingram, 2 years ago

    Currently we use an unpublished (you have to run it locally) Jekyll site with a decent documentation theme, but one of my goals is to convert it to Vuepress and put it up on GH pages so the team has easier access and it comes with built-in search and other useful components.

    I like documentation that is done in markdown to allow for easy export/import into other systems if necessary.

    1 point
  • monaalexandra -monaalexandra -, 2 years ago

    Yes, I'm interested to know as well! I haven't found a good tool, yet, that works for designers and developers alike. We try to manage our way with simple "readme.txt" files on our shared server… but as you might guess, this is NOT pretty nor practical.

    1 point
  • Taurean BryantTaurean Bryant, 2 years ago

    Basecamp does a nice guy publishing all of that in a handbook repo.

    1 point