We're currently using a Wiki, but we're not happy with the manual structuring required and aren't very fond of the Wiki Markup. As a second option, we're using a shared OneNote notebook for meeting protocols, ideas and notes. It's great from a usability side, but I think it lacks permanence (it's just a notebook after all).
Are there any solutions you can recommend? Must be hosted on premises, and ideally requires no large-ish setup or configuration.
Lennart
Posted on
Where do you keep non-code documentation, such as architecture explanation or research?
For further actions, you may consider blocking this person and/or reporting abuse
Oldest comments (55)
I've used github's wiki in the past but eventually information would also end up on google drive. Would love some insight on this question as well!
I really like GitBooks. (see: gitbook.com) It reminds me of an old school SOP when they lived in three-ring binders and had handwritten content pages in the front.
Not sure what 'hosted on premises' means, so there's that :D
It means that it should be hosted locally somewhere in our local network. So no cloud services or something, we don't want to put that kind of data on other people's servers.
All GitBooks are essentially just Git repositories, which can be self-hosted. If your organization requires it to be hosted on premises I suppose you have a self-hosted Git service like GitLab.
In that case, GitLab Pages plays well with GitBook using GitLab CI. Otherwise, you can set up some CI/CD pipeline that automatically builds your books for you.
Do you use GitBooks throughout the entire org -- i.e. sales/marketing docs or strictly for technical documentation?
For everything!
I've never been happy with anything I've tried, so would love to hear other people's thoughts and opinions on this
We have an internal WordPress blog for explaining algorithms, new functionality or research, but it's not the best solution for all developers as some find it very difficult/cba to find the time to blog their ideas/findings. I personally use Evernote for my own notes and share these with people when they happen to work on a piece of code which I've worked on or had some ideas about alongside the WordPress blog. But we don't have a one size fits all solution... Looking forward to seeing others input :)
Our team uses Confluence within the Atlassian suite. Works fairly well for the intended purpose, and it's easy to use. Creating a page is more like creating a word doc than a wiki. I like it better, but those are the only two solutions I've ever used. ¯_(ツ)_/¯
Same here, confluence does the job..... I wish they improved their markdown support though
I miss their wiki markup support. They seem pretty investing in their wysiwyg editor... :(
still a newbie, so this hasn't come up for me yet, but would love to see what everyone else is using, for future reference!
My only complaint with OneNote shared Notebooks in they are very slow in-browser, otherwise I love them (My robotics notebook is public for instance) . I like GitBooks as long as everyone involved knows git (you could host git on-premise, I've never done it so I can't speak to the ease of it)
We are using GitLab and with the latest CE it also has GitLab Pages included. Which is like github pages.
I also loved the idea of runbooks, which is also from GitLab <3 Where you collect all valueable information in one place.
So we have one repo which covers infrastructure, smaller howtos, information about staging, deployments, styleguides, coding conventions, etc. in that repo.
For static generation we use GitBook with the FAQ theme. It's it really nice, because of the GitLab CI runner you only need to push your markdown files and it will build it.
However we also have some project related things in Confluence. Which is a bit, clumpy for my taste. It got a hell lot of features, but is kind of slow and... does not feel that good.
The first place I am searching for docs is the place where the project is. In Version control. We currently are using a mixture of internal wiki and OneNote. But we are slowly migrating to Markdown files stored next to the code.
We're using Quiver in my research lab. It meets all of your requests and then some:
The downside: it's MacOS only.
Quiver looks really solid, but I'm kind of flabbergasted by their choice of only offering MacOS. That seems like a real problem on lots of fronts. I know cross-platform is easier said than done, but it seems like a possible deal-breaker. And I say that even though our whole team happen to be MacOS users.