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
Top comments (57)
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!
We use Confluence (along with JIRA and BitBucket Server) and it's a bit of a clusterfuck. No one really uses Confluence because it's extremely hard to find anything when there isn't anyone managing it and keeping it organized. It's a repository for a lot of documentation. Often times JIRA tickets and git commit messages are a far better source of documentation in the code than Confluence.
Other downsides to Confluence are cost, maintenance and lack of standard (i.e. markdown) support.
This says a lot about other options though: Everything else we've considered doesn't do any of this better.
Our Confluence turned into a total clusterfuck until we realized the importance of wiki gardening. I had to put on a bit of a deletionist hat, which helped, but the real win was developing a standard page organization format for documentation. Every project is laid out in the same way, with the same type of documentation in the same place.
Since search sucks soo bad in Confluence, the rigid layout guidelines made it useful again.
We also use Confluence (along with JIRA) and I agree that JIRA tickets and git commit tend to be a better source of doc to understand what components do. Confluence seems powerful but it's not intuitive and requires time to manage/organise.
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... :(
We started with a wiki (since we were on GitHub, we used the one provided with our main repo). We eventually switched to using a separate repo containing only markdown files named
metafor all of our documentation, including research, best practices, corporate how-tos like expense reporting, time off protocols, etc. We even had a page dedicated to the memes we use in chat, so new team members could figure out what the heck was going on.We found using a markdown repo gave us a few advantages:
Disadvantages:
You mentioned some non-technical documentation is in the repo too -- how have non-devs managed to deal with that? Do your non-technical teams use a different system for documentation?
Since we were a GitHub shop, we just had the greater product team (product management, customer success, etc) set up GH accounts, so that any URL to documentation was accessible. That at least gave everyone read-only access to the docs. We did end up teaching some of these people enough git-fu so that they could contribute, as part of their professional development, and that was well-received. But I did feel this setup was more dev-centric than I would have liked, and it ended up duplicating some information that was contained elsewhere, like in the employee handbook. But I have a violent allergy to both SharePoint and Confluence so this worked well enough for us.
The problem with wikis is when you want to relate your notes to your code (and ideally, that's what you want to do).
I created Code Story to address this issue. Have a look ! I'll post about it soon.
Our team of approx 60 devs are using Atlassian Confluence. The choice was really simple, since we had an existing wiki, and our company moved to the Atlassian suite of products.
We've also focused on documentation that describes behaviours of systems and across systems. So most of it actually reflects what the intent of the code is. Capturing intent and being able to track decisions / choices and motivations over time has allowed us to actually have useful documentation that allows the next developer / tester / ops / whoever to get up to speed relatively quickly.
It's also a wonderful source of group decisions / goals when starting projects, that give a lot of context into why code has been written in a certain way.
I'm not a huge Jira fan, but Confluence is super easy, straight forward, and quite intuitive in comparison.
We have tried with google docs, but that's never worked well enough. too ad-hoc, hard to navigate and discover things in the structure, and... It almost hurts to say it...Confluence has great Jira integration that makes life easier for us 😁
Right now I'm using Notion for personal notes, dumping some stuff into the github wiki, and putting stuff I may need to share into onenote (because the rest of the team is using it). Previous job we used 100% confluence, which was ok because it integrates well with jira.
All I want is a reasonable editing interface that handles markdown-like formatting, including easy code formatting, and a way to share with a team. Bonus points for easy linking to github/asana issues, even if I have to write the macro/shortcut myself. Notion is ok, but is really opinionated about how you'll structure your text and has a couple quirks/bugs that deeply irritate me.
We're using confluence with a template page hierarchy. Something like:
The latest version of Confluence lets you copy the whole page hierarchy and do a find/replace in the title of the pages.
I'm not sure if Confluence counts as a 'large-ish setup'. It requires a database, and it is a java webapp, with all the infrastructure that implies. It hasn't been too bad for our team, though. On the positive side, it gives you a wysiwyg editor
Day job: team foundation server, team build, visual studio, sharepoint, office 365, onedrive. The integration between all the tools is very well done. Visio diagrams for architecture. If we were a small business, I'd push for visual studio team services.
Other job: confluence, gitlab, jira. Has giant gaping holes where features should be. Terrible integration. Just terrible.
Edit: doesn't really answer the question. A well architected file structure is great with appropriate office doc types, sharepoint as a UI with all the other integrations. The other company doesn't do much when it comes to documentation.
What are the gaping holes? I'm in a confluence, jira and kallithea shop, and maybe I just don't know any better, but I haven't noticed any gaping holes.
I would like organizing documents to be easier, so I really want to know what I'm missing!
Probably just the company. Their jira instance looks like a combination bug tracker and project management tool. No test case management (admittedly, after a quick googling, I see there are plenty of add-ons that make me wonder why none are installed). Also no source code integration. I believe there is a gitlab integration available for jira - I don't think they have it set up. But even if it was set up, there's no IDE integration for updating an issue and triggering the workflow. Are there only "issues" in jira? I don't see different issue types with different workflows.
Their confluence looks like a social platform for IT rather than a project document workspace. I will say that it has a nicer UI than sharepoint. I'm not sure how it handles document versioning, checked-in/out states - I don't use it that much. Also, I don't know if it's possible to link confluence documents to jira issues (I see you can attach documents to issues, but not link unless you manually paste a path in there), I can with my TFS work items and Sharepoint docs.
Regardless of the misuse of the applications, the integrations overall are too weak for me in this stack. I want something like in this diagram (assuming a work item has a time element for project management purposes): i-msdn.sec.s-msft.com/dynimg/IC749...
There are JIRA integrations for intelliJ and eclipse, but you have to set those up, and have your source control integrated too...
JIRA lets you define as many issue types as you want. I think "Bug" "Improvement" and "New Feature" are the defaults, but my shop has a number of other types. Likewise with workflow, you can make per-project, per-issue type workflows. I believe you can add as many workflow states and transition as your heart desires, but again, it's manual work.
Thanks for the MS tool rundown, I appreciate it!
We use confluence. The hardest part I found about documentation is writing it. To encourage continued documentation, I have suggested in the past to at least create a page in your tool, prefix it with "DRAFT" and at least do a brain dump or even copy paste from past conversations. At least that way, the knowledge isn't lost. I've found that has time goes by, I eventually go back and start cleaning things up and eventually end up with some pretty clean documentation.
For personal documentation, I follow the same thing but with evernote.
By simply having the data somewhere, it can at least be indexed and searched even if it's ugly.