DEV Community

Lennart
Lennart

Posted on

Where do you keep non-code documentation, such as architecture explanation or research?

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.

Top comments (57)

Collapse
 
juanita profile image
Juanita Soranno

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

Collapse
 
lennartb profile image
Lennart

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.

Collapse
 
irvinlim profile image
Irvin Lim

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.

Collapse
 
jess profile image
Jess Lee

Do you use GitBooks throughout the entire org -- i.e. sales/marketing docs or strictly for technical documentation?

Collapse
 
juanita profile image
Juanita Soranno

For everything!

Collapse
 
jimmy0x52 profile image
Jimmy Mooney

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.

Collapse
 
monknomo profile image
Gunnar Gissel

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.

Collapse
 
grappleshark profile image
Tanja Lichtensteiger

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.

Collapse
 
kaydacode profile image
Kim Arnett 

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. ¯_(ツ)_/¯

Collapse
 
kpath001 profile image
Kevin Path

Same here, confluence does the job..... I wish they improved their markdown support though

Collapse
 
monknomo profile image
Gunnar Gissel

I miss their wiki markup support. They seem pretty investing in their wysiwyg editor... :(

Collapse
 
jwrubel profile image
James Wrubel

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 meta for 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:

  • Changes to the knowledgebase could use a pull-request model, allowing for come amount of discussion and consensus before they were added.
  • Markdown is already familiar to everyone, and being git-based means you can access it offline through your cloned copy
  • The team is pretty quick at writing markdown so it was useful for recording meetings and decisions in real time, and then just committing the change later
  • Search - either using git grep or, since we were on GitHub, just a browser
  • Developers are at the command line anyway so this was a familiar workflow

Disadvantages:

  • It made is basically impossible for non-developers to contribute, or in many cases, to even access it
  • Linking between pages is all manual (wikis and other tools generally do this pretty well)
  • Link rot and page rot (but I think every tool is at risk of this)
Collapse
 
jess profile image
Jess Lee

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?

Collapse
 
jwrubel profile image
James Wrubel

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.

Collapse
 
dperetti profile image
Dominique PERETTI

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.

Collapse
 
pavsaund profile image
Pavneet Singh Saund

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 😁

Collapse
 
antislice profile image
GA

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.

Collapse
 
monknomo profile image
Gunnar Gissel

We're using confluence with a template page hierarchy. Something like:

<Project>
    Getting started with <Project>
    <Project> Processes and Procedures
    <Project> Architecture and domain
    <Project> Operations
    <Project> Active Development Projects
    <Project> Planning
    <Project> Staff and Organization
Enter fullscreen mode Exit fullscreen mode

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

Collapse
 
antonfrattaroli profile image
Anton Frattaroli

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.

Collapse
 
monknomo profile image
Gunnar Gissel

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!

Collapse
 
antonfrattaroli profile image
Anton Frattaroli

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...

Thread Thread
 
monknomo profile image
Gunnar Gissel

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!

Collapse
 
thecodegoddess profile image
TheCodeGoddess

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.

Collapse
 
bojanv91 profile image
Bojan Veljanovski

We're using DocFx as a tool for building our Wiki pages. It supports Markdown. dotnet.github.io/docfx/ Basically, we host our markdown pages in local GIT, and then build the static site from command line.

Collapse
 
colematt profile image
Matthew Cole

We're using Quiver in my research lab. It meets all of your requests and then some:

  • No manual structuring required. It supports Markdown, WYSIWYG text editing, even a subset of LaTeX. It has built in code formatting for code blocks.
  • Plays nicely with version control software since all the notebook content is stored as JSON. So you get a nice wiki-like presentation plus HTML/PDF output if that's what you want.
  • Hosted on premises? Sure. The JSON files go anywhere you want, including local storage, network storage or cloud storage.
  • No setup or configuration beyond installing the program.

The downside: it's MacOS only.

Collapse
 
ben profile image
Ben Halpern

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.

Collapse
 
rdmueller profile image
Ralf D. Müller

Great question!

I use AsciiDoc (methods.co.nz/asciidoc/) to write my docs and treat it as code (search for "docs-as-code" or "docs-like-code"). So I just store it along with my code or in its own repository if it belongs not directly to the code or is written before you code like architecture docs.

Most git frontends like bitbucket and github support the direct rendering of AsciiDoc, but I've build up a toolchain which helps me to maintain my docs. It is called docToolchain and can be found on github: github.com/rdmueller/docToolchain

It helps me to automatically update diagrams, render the docs as PDF or publish it to Confluence. The Confluence feature is IMHO the best - it allows you to let people read your docs in a wiki while you maintain them in Git.

A presentation on the thoughts behind it can be found at speakerdeck.com/rdmueller/thhg-to-...

Collapse
 
thetuftii profile image
Claire Pollard

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 :)

Collapse
 
phansch profile image
Philipp Hansch

We use yard (a ruby gem) to generate code documentation and also static project overviews, runbooks/workflow guidelines, many howtos and troubleshooting guides.
This works well as all changes to documentation are in version control and have to be reviewed.
The tool generates static HTML which makes the deployment of the docs pretty straightforward.

And then Google Docs/Drive for keeping meeting notes or collabarative planning of features. Google Drive makes file management hard somehow, but the search always works.