image created by Margaux Peltat for the Chilled Cow YouTube channel
Time for #DEVDiscuss โ right here on DEV ๐
Inspired by @tyagi_data_wizard's Top 7 post, tonightโs topic is...documentation workflows โ๏ธ๐๏ธ
Questions:
- What documentation processes, workflows, or "hacks" have helped you or your team?
- What docs processes, workflows, or "hacks" have failed you spectacularly?
- Which tools do you use for documentation?
- How do you combat sprawl and duplicates in your documentation efforts?
- Any triumphs, fails, or other stories you'd like to share on this topic?
Top comments (14)
I'll kick it off today and say that I'm Team Notion for documentation! I love a nice, clean, modern database. It does lack in some automation I'd like, although I'm sure I could engineer some automation solutions if I had the time and know-how. But I'm a sucker for good visual design and Notion can't be beat in that regard, imo.
I love Notion (aka Stella) we have been together for a long time
Is there a way in Notion to export all data as a repository of Markdown file? Not just one file, the whole lot.
That's the one thing I don't like about Notion, it feels like I am giving away control of my own words to a company.
UML failed as too static and not growing with the code. Now shifting to architecture decision records and C4 model with its own DSL to create architecture as code that can change during pull requests. Let's see how this will work out.
For my Java libraries, I use javadoc to generate the docs, the obvious choice for Java. But I also host the docs via GitHub Pages, and automatically update the docs site on each release using GitHub Actions. I use a couple Actions I've implemented in the process. An Action javadoc-cleanup enables post-processing the javadoc output such as injecting stuff into the head like canonical urls for each page, the site's favicon, etc., and I generate a sitemap with generate-sitemap.
I had a post a while back here on DEV about my documentation workflow:
Deploy a Documentation Website for a Java Library Using GitHub Actions
Vincent A. Cicirello ใป Nov 30 '22 ใป 9 min read
We have a DocFX project where my devs can write documentation in Markdown which is published by our build server when they commit and push. We aim for information over perfection, which is basically get some notes down and commit it instead of waiting for the perfect time to write up some 100% formal documentation.
We treat each page as an "article" which of focussed, only low level when it needs to be, and logically grouped together. High level descriptions of software processes are favoured over line-by-line documentation of code. Snippets of code are included but are for demonstration as opposed to saying what the code does. For example, within a guide on how to implement an abstract class.
The code itself should be as self documenting as possible, with not too many levels of abstraction and meaningful names etc. The code is the low level documentation, the documentation is high level.
We've broken it into three main areas.
As for things we've done wrong. We're always learning and improving but there are some definite missteps (some due to ignorance, some due to not having access to tools back then). We used to have folders of Word documents, but they were hard to find, slow to load and of differing sizes. So documentation went unread frequently. Then we used OneNote which was an improvement due to the collaboration aspect. However the flexibility of a giant notebook was good but it also got messy and disorganised fast. The DocFX solution has been the most successful so far, with more developers reading the documentation than ever before. They share it between each other, and are going there first when they want to know something.
Like I said there's always improvement to be made, but the success comes from two points:
I'm genuinely curious, in a corporate environment, as to the amount of Write-Only documentation you feel you write?
Myself, I feel like most of my documentation is Write-Only. We use Confluence and even though it's search hands relevant documents as the literal first result, I'm constantly asked for it. When handing those documents to people, they just want me to walk them through it again. On asking what is wrong with the docs (worded more like: what needs to change?, what is missing?) I'm told they are great.
I believe a big part of this is we have a lot of VERY niche people. Their technical skills are DEEP in their one area and anything outside of that is ยฏ_(ใ)_/ยฏ and where we have problems are when they are asked to do things outside of their tech silos. My own bias here is that I'm a generalist by nature (ADHD as the excuse why I can't focus exclusively on just one tech silo) so to jump into a new tech (such as GIT) isn't as much of a barrier and reading docs to learn is second nature so not doing so is alien to me.
We have 100s of projects and a soft-req that each thing has updated documentation (detailed technical, detailed user docs and detailed support docs) and I honestly fight back on the scale of docs asked for that as most of it is write-only.
//finished ranting :D - for now -
The problem is that Confluence sucks for finding the place where you wrote the damn thing. People usually don't go there, but if they do you need to give them yourself the link. This is so so bad.
I'm really curious how LLM AI is going to change the way documentation is created, consumed, and updated.
There is already plenty of tooling that has come out since ChatGPT was demo'd, but I suspect we haven't really figured out what is truly the new standard expectation for this yet.
I write almost no documentation. Code is either self-documenting, or structured such that replacing it should be easy, and business cases are impossible to sensibly write down - wetware remains king, if you can get enough people to cover redundancy. Write software that is easy to replace and easy to modify. Write APIs that document themselves. Write documentation only if you need to explain something thrice.
I do all my writing in Obsidian which you use similar to Notion, but technically it's more like VS Code for writers, basically a navigator with an infinite amount of plugins.
I have already 381 files and 12k lines of text here, something I would have never expected when I started.
The main process I recommend if you want to fail spectacularly is to try to write a big article all at once until it's perfect.
Rather I recommend writing a shitty first draft, without judgement, without ever pressing the backspace key.
Later I will refactor things.
I already gave that tip from Anne Lamott, the new idea now is that ChatGPT is often perfect for generating that shitty first draft. No blank page syndrom anymore, that's a big deal.
I've discover that scheduling is really important. I would recommand to always schedule your post. It removes the pressure "is my article ready yet?". Who cares, you schedule it for Monday 09:00. You can always improve it until then. And once it's published you are not refreshing your notifications like "oh I hope someone like me and has giving me an emoji". Instead you forget about it and it's a nice comment that reminds you that indeed you have published something.
I also recommend picking a pace. For example I will try to post ever Monday at 09:00. Which pace? Every day? Every month? There is no rule except that the pace suits you. We are creature of habits so this really gets you to the next level.
But for me the biggest win was to use a Swipe File from which you pick your article ideas once you start writing. So you never again face an empty screen and ask yourself: "what I'm gonna write about today?". Instead you separate ideation from writing. If you are out in Paris walking your dog and you get a cool idea for an article --> you put in in the swipe file.
The swipe file is a concept, not an app, you can use any app for that, for example Bear(iOS), Google Keep(Android), SimpleNote(All)
The one very important rule is that you must use that note app only for that purpose.
For example with this comment, I have in fact written the More written tips idea from my swipe file :)
My final advice is that writing is great, just do it, don't worry about being bad at it when you start. It's like programming, it's all practice.
Now I just need to embed this comment in my previous writing tips article.
20+ Lessons I've Learned Writing on DEV for 4 Years
Jean-Michel Fayard ๐ซ๐ท๐ฉ๐ช๐ฌ๐ง๐ช๐ธ๐จ๐ด ใป Jun 29 '21 ใป 9 min read
This was a key learning in my creative writing education, too. I lived by the phrase "the only thing a first draft has to do is exist." Otherwise I can get so up in my head trying to perfect the details and second-guessing myself that the draft never gets done ๐ตโ๐ซ
Tbh I don't think I've ever written documentation that was read by anyone else... As a result I only write documentation when a client explicitly asks me to, or when it's some specific business process that I know I wont remember a month from now. In the case of a client request, it's usually in confluence. For my personal notes I prefer notion. I've tried obsidian, but you have to pay for it if you want to sync between devices, which notion does for free.
A mix of jira (which i hate) and markdown readmes in our bitbucket repositories.
I would love to switch to asciidoc (asciidocj) but bitbucket doesn't support it.