What’s your favorite go to documentation tool for building team knowledge base
source link: https://lobste.rs/s/3faroe/what_s_your_favorite_go_documentation
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
What’s your favorite go to documentation tool for building team knowledge base
Hello,
What are you favorite documentation tools for building team knowledge base.
It can be opensource and offer features such as full text search and can be hosted as a static site
-
Everywhere I have worked I have been forced to use Atlassian Confluence, but if I had to choose and I could choose anything I want at any cost, I would use https://www.craft.do/ .
If you are looking for an open source option guess look at some of the self hosted wiki options such as:
https://www.dokuwiki.org/dokuwiki
https://www.mediawiki.org/wiki/MediaWiki
I haven’t used any of them myself to give a recommendation.
-
Text files checked into the source repository. Unix is my IDE.
-
Any old school wiki based on a simple enough plain text format to be written by hand. MediaWiki and similar. Or even markdown based solutions such as Jekyl. Or a git repo with markdown files, or Restructured text, or org files. GitHub and other fit hosting solutions offer formated display of these files in their web repo browsers.
WYSIWYG sounds like an usability obvious choice but that is an illusion. After less than a day of usage you’ll run into absurd sufferable pains because of it.
Documentation is by definition technical. To negate all the advantages of robust, versatile and durable format for the sake of perceived user friendliness is a huge mistake.
I am forced to use confluence because of professional reasons. Literally every day I see some display failure making ng the content scrambled or unreadable, or notes saying “ replace x by y in the text, confluece won’t let me paste the word x”.
-
For markdown based solution, I’d recommend mdBook. Single binary, comes with five themes (one of them can be set as default and user can change it too) and there’s a search option as well.
-
-
We’re trying out Notion.
-
How do you expect this to play out in the long-term? Tools like these can start out well when you have a set of users that span a whole company. Eventually cost, or just a more trendy tool, cause folks to want to move. This is not a great experience for folks, but it seems to frustrate eng teams more than others. I like Notion’s user experience, so I’m more interested in whether you think they can be sticky, especially for eng teams.
-
-
I recommend a VCS(like git) with a bunch of files in it, in some format that makes sense to you(typically Markdown, but whatever). You can spruce it up with one of those wiki products that take files on disk as their storage. There are lots of those, but again, whatever.
The format is basically permanent, it’s in a VCS so history is kept, and everyone can keep their own copies and send updates as they choose.
-
I just built a knowledge site with docusaurus.
I’m not a web programmer, but it was ridiculously easy to set up, and super easy to deploy to GitHub pages. Looks great and you can write content in plain Markdown (.md) or in Markdown + JSX (.mdx).
-
I like hedgedoc but I wish it could be used offline for emergencies.
I wish there was something like logseq with crdt (free and open source).
-
I’ve actually used the Hedgedoc API to extract docs for reuse in a static site generator. It’s not nearly as ergonomic as a native offline mode, but it doesn’t have the benefit of not requiring you to know that you may want a particular doc and preload/save it for use offline later.
-
-
As of now, Google docs for flowing things and the ease of external sharing, and a version controlled docusaurus site for relatively stable things.
-
Markdown in a repository, maybe some graphs, etc if necessary.
-
I think it’s extremely hard to beat markdown or text in a vcs repo. You can use a static site generator to build it and publish as a website if you want that functionality. Lots of git hosting solutions offer in browser viewing and editing as well. For those of us who prefer our own editors we can easily use that. It has the lowest overhead to keep up to date and easiest discoverability I think. You can even have most of the development documentation co-hosted with the application itself which makes it even easier to ensure the documentation is kept up to date via code review checks. Some of them can even be automated.
Wiki’s require extraordinary gardening effort to keep up to date so long term discoverability becomes a nightmare. Wiki platforms all seem to have the worst editing experience as well.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK