How to fix my documenting skills

[-]

Jellovator@reddit

I started using bookstack about 5 years ago. Before that, the IT department had a shared folder where they would dump text files and word docs with into. Anything from procedures to software install instructions to random, oddball fixes for equipment. I just copy & pasted each document into a new page in bookstack, then started organizing. Once I had a folder structure (or chapter structure, whatever) I started working on cleaning things up. A pleasant surprise is that it keeps your Word formatting and images, so a lot of the old documentation was pretty much good to go. But text docs I went back and formatted, added screenshots in some places, etc. But it helped just having everything uploaded to begin with, especially since everything gets indexed and was now searchable.

[-]

ConsoleChari@reddit (OP)

What do you suggest about the structure. I manage everything from networking, vms, identity etc. I should have each in their shelf right? and use links to point to corresponding things

[-]

ssddanbrown@reddit

BookStack dev here, I'd advise keeping to books as the top-level, and treat shelves more like meta-collections (since the dynamic of shelves is a bit more complex, especially if attempting to set permissions at the shelf level). Main thing is to get the information written into pages, you can always re-order if find yourself struggling to find stuff based on structure, once you get a feel for actually using the system for information retrieval.

[-]

ConsoleChari@reddit (OP)

Got it, I ended up doing exactly that just started writing without stressing about structure. Feels way more productive, I can sort things out once there’s enough content.

Btw, thanks a lot for making such awesome app.

[-]

Motor-Marzipan6969@reddit

There's also a Bookstack plug-in that lets you import Word docs directly. I was really surprised by how well it works.

[-]

ssddanbrown@reddit

Link to the hack for reference: https://www.bookstackapp.com/hacks/wysiwyg-docx-import/

[-]

whyareyouemailingme@reddit

This is good to know. We’ve got a bunch of stuff in Google sheets and docs and while I get it, it’s… hard jumping between a Google Drive tab and 7,000 documentation tabs. I’ve been trying to use some downtime to look into a system that might be useful for the future and it’d be helpful to eliminate some of the legwork of reformatting and transferring.

[-]

SevaraB@reddit

Templates. Write templates once and fill in the blanks many times.

What are your routine tasks? Operational playbooks. Who runs what, where, and why (what depends on it).

What do you commonly have to fix? Troubleshooting runbook. What is the app running on, what does it need to talk to and how can you tell it's actually talking, how long can you afford to spend troubleshooting before you have to bring in the cavalry.

I'm heavy into infra as code, so I make documentation with code- I make Jinja templates so that Python scripts can fill in blanks to generate Markdown documents that go into our private Github account (which conveniently offers Mermaid diagrams that can also be generated from Jinja templates). And if we decide to stop using Github, we'll still be able to view Markdown locally- the only thing I'll need to tool for a migration is making sure Mermaid is installed on the next repo provider.

[-]

Curious201@reddit

what helped me was separating “capture” from “polish.” if i try to write perfect documentation while i am fixing something, i usually write nothing. now i just dump the rough steps first: what was broken, where i looked, what command or setting changed, what fixed it, and what i would check next time. later i turn that into something cleaner if it becomes a repeated process. screenshots help a lot, but only if they are paired with context, because a folder full of screenshots without “why this matters” becomes useless pretty quickly. i would start with small runbooks for things you actually repeat, like creating a user, renewing a cert, restoring a file, adding a printer, or troubleshooting vpn. once you document 5 or 10 real tasks, the structure gets easier because you stop inventing the format every time.

[-]

Turbojelly@reddit

Just tyoee it all out in a mess. Then go back through it and organise it to make sense.

[-]

radicalize@reddit

I'd start by thinking about a clear path and approach, what it is that you need to have documented, in writing or otherwise.

I'd start with a generic or high-over approach,: create a detailed visualization of the overall landscape, architecture and/or technical infrastructure that you support;

have a clear view and full insight of processes, applications, functions, vendors, assets, contracts, licenses, and so on - every aspect that is part of the whole ecosystem;

for every component, what is critical, what's important, what's not and continue to the next component until you have a representation outlined.

Than I'd think about what you need to document specifically, things like processes, procedures, standards, guidelines, checklist, manuals, and so on.

It's a journey, and a lot of work (at first), but maintaining should be easier, if you make absolutely sure that the foundation sticks (a framework if you will)

[-]

ConsoleChari@reddit (OP)

As you suggested, I just created an diagram with drawio with all the things I have and loosely add connections which gave me an clear insight on how to structure. then created diagram for common flows gave it to the new hire to go through these and ask me about where he is getting stuck.

now it make so much easier that the overview of the things.

[-]

radicalize@reddit

nice one! Hope it provides you(r team) the clarity moving forward (being in control is key)

[-]

lexxx9694@reddit

From my experience, the best approach is a good search engine to find right instructions. You type in search - "email in phone" and it leads you exactly on how to setup intune on mobile device. Not other 100 useless shit not related to your question.

[-]

Practical-Alarm1763@reddit

Just start writing, don't think and just write it out and provide screenshots. Once you dumped everything in your head into the document with screenshots, use Copilot, Claude, or ChatGPT to rewrite coherently and make it look formal and pretty. Then review the AI generated output for errors and corrections. There will always be errors and corrections.

This is a specific use case where generative AI is actually useful. Take advantage of it, no one likes documenting their work, it fucking sucks.

[-]

justaguyonthebus@reddit

Create a persona of the person you are creating the document for. This will help you keep a consistent level of detail across that type of document. It's ok to have brain dump documents while you work and a separate set of official documents.

[-]

jasondbk@reddit

There are good comments in here.

Start now!

Before you write lots of documents, think about how it will be accessed. But don’t let that stop you from starting to write. Do you want to do an online wiki? Does your company have a knowledge base? A document management system?

The formatting can always be updated later.

My first technical documentation project I was invited to work with the “team”. It was written in a line editor, TSO’s editor for those who are old. We manually wrapped words to new lines. Formatting bold, italic etc used html like codes, the table of contents had to be updated manually. Screen shots didn’t even exist back then!

400+ pages of documents were done this way.

How did it get started? Not with a TOC! It got started with poorly written notes that got reviewed and revised and reviewed again.

Having your new hire do some of the review and revise. It will make them feel like part of the team. They will feel like they are part of the team.

[-]

vinothsomu@reddit

This is very relatable. Do you think the hard part is actually knowing the environment, or converting what’s in your head into a clean doc structure?

I’m trying to understand this workflow pain: if you could just talk through the setup/process for 5–10 minutes first, then convert that into a draft SOP/wiki page with headings, steps, checklist, and notes, would that reduce the friction?
Also, what usually blocks you most
1. deciding the structure,
2. writing clearly,
3. knowing how much detail to include,
4. keeping docs updated later?

[-]

RustyRoot8@reddit

Claude is good at organizing Obsidian notes and creating standard documentation too

[-]

Lanky-Storm7@reddit

I have Claude doing a fit lab repo and I have it make an me on everything in my infra. Anytime I work on something I walk Claude through it and have it write it and commit to the git. Then other people can clone it

[-]

Disastrous-Mammoth75@reddit

Any documentation is better than no documentation. Brain dump now, polish later. Better yet, have your junior polish as they use what you’ve put in there—then you’ll know it makes sense to someone other than you!

[-]

Th1sD0t@reddit

Out of curiosity, would one prefer obsidian over OneNote or vice versa? And why?

[-]

whyareyouemailingme@reddit

Obsidian’s graph view scratches an itch in my brain. Also it’s markdown, which I personally find faster for formatting.

[-]

Valkeyere@reddit

Its important that documentation follows guidelines for format and structure. Otherwise it grows to the point of becoming useless as you cant find what you need so presume it isnt written yet

Make sure to not rewrite anything.

Make documents as granular as possible and interlink them.

[-]

ThatsNASt@reddit

I know I’m probably going to get some flack. But I’ve been using Claude to basically take my very basic documentation with screen shots and prompt it to make me a better SOP or kb in markdown/html. It has saved me hours.

[-]

ntrlsur@reddit

Just start putting in. Don't worry about anything else. Get it documented. Bookstack as a pretty good search and you can find what you are looking with ease. When you or the PFY stumble on a page to look something up evaluate it then. Make changes add or subtract information screenshots etc.. As you go on and touch the document it will evolve. For our bookstack instance I made a few chapters servers networking etc... then justmake the page. you can move it around later. You can also link to it from somewhere else. The most important piece is just to start documenting it. The rest will fall into place.

[-]

ProfessionalWorkAcct@reddit

I connected Claude to Notion. You could use OneNote or just Word on a Sharepoint site.

It writes the pages and the documentation for everything now.

You can send claude the screenshots of your configs or straight up configs of your switches/firewalls and have it document everything. I am not kidding, literally everything. Intune, AD, Entra, Azure, Power Automate, even something new you're working on, you can make it keep a page updated and then finalize it when the product/solution is done.
Your new hire can then connect his Claude to the Notion pages and then it can explain to him the documentation.

Please get yourself an actual Team account for Claude or whatever AI you're going to use, so your entire environment doesnt become part of the next model.

[-]

FastFredNL@reddit

My advise is to not just start writing all the documentation in one go. I treat it the same as my password manager. So whenever I do a task I just think 'Oh, gotta document this' and I write up the steps that I perform. And it's mostly ment for IT people anyway so I just roughly write up the steps and were to go.

Only when writing out steps for endusers do I add pictures and circle the buttons to click lol

[-]

Darkone06@reddit

Honestly this is the kind of stuff that Chat GPT excels at. Give it a screenshot and tell it to create a guide to install or troubleshoot this issue. If you need additional steps vaguely word it in the chat and watch it create the document you need.

I have a tab just got creating documentation and one for creating tickets.

Ticket documentation rewrite: Create a tech documentation for end user based on this screenshot error explaining that you need to install and run VPN before they can use this software. Our VPN software can be found here and our VPN server is VPN.BigCorp.com

I have lately gone back and created a lot of needed documentation and have received really high praises for the amount of documentation I'm doing and the quality.

[-]

blairtm1977@reddit

Man. I use Scribe. I was like you. All in my head. So I just tuned on Scribe and went through the normal process. It took all the screen shots. I just added the headers and info. Export to PDF and put into document control.

[-]

H0verb0vver@reddit

Pictures say more than a thousand words so yes, highlight the buttons in the screen shots. Keep your text short and let the image speak for itself, with just small guidelines.

[-]

Ghelderz@reddit

That’s so funny to me as I have the exact opposite opinion! GUI’s change all the time and it’s hard to keep up! I much prefer detailed written documentation.

[-]

radicalize@reddit

Which seems strange to me in and on itself. If the approach changes to a certain process, because of UI/UX changes:how is writing about this easier than updating a screenshot and some clearly written guidance ?

[-]

whyareyouemailingme@reddit

Sometimes it’s easier to have the written text too if it’s particularly long so Ctrl+F can help while I’m clicking around trying to find something. Just my $.02…

[-]

Hg-203@reddit

My issue with that is when the gui changes and you can't find the words you wrote down. I can grab context clues by what was in the old screen shot, and how it compares to the new screen shot. To figure out what the GUI is trying to do.

While I'll some times go back and mark up the screenshot. Future me will be just happy with an non marked up one that shows me what was there before.

[-]

rubmahbelly@reddit

Ignore everything regarding formatting. Write in a editor in plain text.

When done copy paste and then do the formatting.

I had a similar problem with a wiki we used and it distracts me too much.

Hth

[-]

ConsoleChari@reddit (OP)

I definitely felt same way. While writing I was always worried about formatting. will try having it in raw text tomorrow.

[-]

itishowitisanditbad@reddit

Don't worry about perfection, just get something down

100%

I'd rather have something with clues than nothing with nothing.

Even if it sucks, even if its scribbled notes, whatever.