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.

Latest comments (55)

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
 
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
 
asynccrazy profile image
Sumant H Natkar

We keep it in our source control

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
 
hexhead profile image
Bill White

"What are you talking about?" -scientific programmer

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
 
radioakt profile image
James Audry Spencer

Google Cloud, top tools 👌

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