DEV Community

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

Lennart on May 03, 2017

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,...
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
 
phil-hansch 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.

Collapse
 
apertureless profile image
Jakub Juszczak

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.

Collapse
 
nodebotanist profile image
Mx Kassian Wren

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)

Collapse
 
phlash profile image
Phil Ashby • Edited

My colleagues in technology and I like to keep all the docs with the code in source control (preferably in Markdown, Gherkin or other change-control friendly formats), however we're a multi-stack shop due to a number of acquisitions, legacy technology stacks, etc, so we have multiple solutions:

1/ Almost everything in TFS/SharePoint, now migrated to VSTS in the cloud (not good for the OP), aka the full Microsoft solution - this works pretty well, including less-techie access and editing via the VSTS web GUI for requirements management, design reviews, etc. Project control is via Aha*, which integrates with VSTS ticketing.

2/ The Atlassian solution, Confluence + Jira + BitBucket Server, also being migrated to cloud versions (we like the cloud!) - thus far unable to hold confluence pages in BitBucket, so not really connected together, but a good UX with cross-referencing, and excellent for less-techie access. Aha again integrates with Jira for project control.

3/ The random document clusterf*ck - not my favourite approach but still rather popular, especially when documents or information are sourced from outside the business and helpfully emailed round the team(s), or dumped on a non-versioned shared drive (we're trying to kill this!). Some sanity is usually created through a common project document structure, and encouraging outsiders and their internal reps to feed into Aha as a common information point.

Collapse
 
rmorschel profile image
Robert Morschel

We use System Architect, but most people hate it. If you have a decent Wiki like Confluence, you have a decent environment to architect in. Gliffy or PlanUML for diagrams, and normal wiki for the rest. I hardly ever drop into markup.

Collapse
 
sstubblefield profile image
Scott Stubblefield

Following. I've helped initiate a new set of docs at my company over the last couple of weeks, and we're currently in this dilemma. We were using Confluence to keep important info, but it just feels so detached from our workflow. We've started including a more informationally verbose readme in our project files, and eventually decided to build our docs in ButBucket. I don't know if it will stay that way, as we're still discussing whether or not the Project Managers should learn Markdown and the basics of Git, in order to maintain docs from their end. I'd love to eventually see a better solution, such as a front end wysiwig that converts rich text into MD, and ties into a repo.

Collapse
 
rubberduck profile image
Christopher McClellan

I've honestly yet to find a solution as good as markdown files in the code repository for technical docs and google docs for "businessy" type of documents, meeting notes, estimates, etc.

I try to keep architectural docs right with the code, then process them to PDF with pandoc if there's a ever a need to share those outside the team.

Collapse
 
saschadev profile image
Der Sascha

We use confluence for documentation. Now we have a single point for a documentation. For our supporter we use SharePoint with the Integrated search. Because this is times faster as a huge confluence database search.

Collapse
 
bitauction_de profile image
Bitauction

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.

Collapse
 
rouzbeh84 profile image
rouzbeh

notion.so is pretty great for me and gets a lot of updates! once you give it a hour or two and sort of absorb the 'block' structure the slash commands and nested pages + columns is quite an amazing feature! it all depends on what kind of documentation i'm working on though, for code I like to just use a pattern library, for text dropbox paper is very nice.

Collapse
 
saxmanjes profile image
Jesse Piaścik • Edited

I keep them in my github repo. I create user stories in markdown files and organize my work with imdone-atom and import my TODOs into github issues with imdone.io. It keeps me from context switching while I work and keeps my issues in sync with my TODO comments. You can read more about it here

Collapse
 
seanability profile image
Seanability

We spread it around multiple, disparate systems so that no one can ever find what they need. The best way to find information at my current client is to email 30 people for days on end.

Collapse
 
david_j_eddy profile image
David J Eddy

Confluence...'cause Atlassian owns our soul.

Collapse
 
jbwebtech profile image
jbwebtech

Spit, duct tape and Confluence. Some days I think the duct tape wins.

Collapse
 
hexhead profile image
Bill White

"What are you talking about?" -scientific programmer

Collapse
 
ribugent profile image
Gerard Ribugent Navarro

We're using google drawings for diagrams and charts, and a wiki(mediawiki) for the docs.

Collapse
 
asynccrazy profile image
Sumant H Natkar

We keep it in our source control

Collapse
 
aravind profile image
Aravind Putrevu

Depends some use share point, one drive in MSFT world.

Nowadays confluence

Collapse
 
nocyamb profile image
Nocyamb

Redmine, project's wiki

Collapse
 
meuon profile image
Mike Harrison

Dokuwiki. dokuwiki.org/ - Even if it's what you aren't happy with it, it can be extended with a few modules.

Collapse
 
antoniwan profile image
Antonio Rodriguez

Google Drive! But now that I learned about Quiver in this thread, I'm checking it out. 😂

Collapse
 
smulholland2 profile image
Steve Mulholland

Redmine. Has a wiki, git integration, file storage and easy to use project management.

Collapse
 
mariomarroquim profile image
Mário Marroquim

I use a wiki for each project.

Collapse
 
shanise profile image
Shanise Barona

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!

Collapse
 
djviolin profile image
István Lantos

Any research kept in a NOTES.md file in the repo, because I don't want to spam the README.

Collapse
 
kostjapalovic profile image
Kostja Appliku.com

Gitlab ticket or Gitlab wiki pages. Uses Markdown, lies in same project, can be linked form other Issues/wiki pages.

Collapse
 
radioakt profile image
James Audry Spencer

Google Cloud, top tools 👌

Collapse
 
tanyapowell profile image
🌟t powell 🌟

I've never been happy with anything I've tried, so would love to hear other people's thoughts and opinions on this

Collapse
 
jess profile image
Jess Lee

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!