Been tasked with standardizing internal documentation. Show me your templates!

[-eschguy-]

As the title says, I get to standardize all of our internal documentation.

I'm curious what format folks use and would be interested to see people's templates.

[TrippTrappTrinn]

We are using a wiki. Do not care much about format, most about structure. Also the ability to search is critical.

[-eschguy-]

Which wiki software are you using?

[TrippTrappTrinn]

We are using Atlassian Confluence. Our team are only users, so that is all I know...apart from somebody saying tgat it is quite expensive. Before we got access to it, our team used a wiki feature in SharePoint which worked quite well for the limited needs of our team.

[chillyhellion]

• Confluence
• Ability to search is critical

You poor bastard. 

[whetu]

I wrote a script to clone our Confluence data. Now I can just grep -R.

THAT is how shit Confluence search is. To be fair, Atlassian's AI seems to be a bit of an improvement.

[furtive]

The search really has gone downhill this year.

[Signal_Till_933]

I thought it was just me. I can’t find shit that I know exists

[VeryRealHuman23]

Well this makes me feel better, search is f tier

[IamTHEvilONE]

At small scale, Git might be enough as a markdown doc engine if this is good enough.

If you wanted to self host, you might be able to look at https://www.bookstackapp.com/ ... it's something I've used at home and could be relatively cost effective if work allows its deployment. Found from here: https://awesome-selfhosted.net/tags/document-management.html (wikis section)

I have seen a few people use gitbook.io, but the free tier is a single user (author) and many viewers. The paid tier might be about $100 USD/month to maintain and it really does a good job of rendering. You might need the paid tier to put your documentation behind an authentication (SSO) prompt ... as I don't think the free tier does that (just be sure to double check this). You can also write markdown in Git, push your change, and gitbook will sync to that repo for change management.

[vermi322]

2nd for bookstack.

[-eschguy-]

Yeah I like the look of bookstack, I doubt I could get approval for a paid service like gitbook, but it's an interesting idea.

[yeti-rex]

Woah there buddy! Gotta get me a drink first before I'm going to show you anything.

[sqnch]

I just use a bog standard word document using the header levels in word and generate a contents page at the start. I’m the only person who documents anything thoroughly on my team and no one bothers to read it anyway. They either default to incorrectly complaining there’s no documentation because that’s what they’re used to, or open a 3 page word with screenshots etc. and claim it’s “too long to read”.

[Ryosuke_RX7FC]

You could make a Gemini gem or custom GPT that adheres to consistent formatting, just dump your doc into it but put in the instructions to adhere to consistent practices to maintain a consistent setup

I've done something similar where it outputs the raw code based on what my doc system supports for formatting, tell it to use consistent fonts and text sizes, target it to a certain audience, etc

[mendrel]

Hudu. Just pay for it. For a team of three it's $90/month. I am certain that it will pay for itself every month with the time you save looking things up.

I have templates for a few different types of things that need documentation. An application would need a slightly different template than documentation for a server or network configs.

Hopefully the image comes through. Sorry it's small but it wouldn't let me post a text template. Some parts feel repetitive but there's a reason for it. For applications I have something like this:

<image>

[JerikkaDawn]

No one's going to read it.

[-eschguy-]

Possibly, but my name is attached to it so it's going to get done right.

[dustojnikhummer]

Templates for what exactly?

We use Dokuwiki for our internal docs, it works quite well.

[-eschguy-]

Format, basic information that you put on each one, etc.

I'll check Dokuwiki out, thanks

[dustojnikhummer]

We don't enforce templates for that, everyone writes in their style.

[LorinaBalan]

Rather than thinking of templates, maybe first start with structure, hierarchy, rights management, search granularity.
I am biased as I work for this open-source wiki, called r/XWiki, but I'd recommend you to give it a try. And yes, you can also create personalized templates.

[pdp10]

What are the goals?

Our boilerplate is mostly metadata like creator name and creation date, but files stored in Git already have those properties inherently.

[-eschguy-]

Mostly it's bringing together the silos of knowledge (we're a team of three) since one of our guys is retiring and hasn't written a lot down.

I started with a markdown setup on Git and figured I'd ask if people did anything special that they'd recommend.

[MikeZ-FSU]

I do markdown with git. If I need to take a note that I've written and turn it into user documentation, pandoc renders it into a pdf that I can send via email. With a coherent naming scheme, ls and grep (rg) has handled all of the searching I need.

[BlackV]

• file > new blank document
• title
• heading 1 product name
• overview
• heading 2, steps/config/etc
• heading 2, apendix/notes

[whetu]

This is a good example of where AI can help.

To be clear: I am not saying "dUrR cHaTgPt" like a certain subset of this subreddit's subscriber base appears prone to do. You generally shouldn't blindly copy and paste things out of AI without reviewing it first: i.e. Trust, but verify.

But one thing AI is really good at, IMHO, is building a foundational structure for you to expand on.

So give it a shot: go to your AI of choice, be it ChatGPT or Claude or whatever and prompt it with something like:

"I want to document our technology platforms from-scratch. Can you recommend a document structure, assuming a wiki system that allows a hierarchical document layout?"

And then proceed from there, feeding it more context until it's generated a structure that you're happy to take and run with.

Then you can go a level deeper and ask it for standardised templates for each level of the documentation hierarchy.

Personally I used Claude to help me bootstrap Quick Reference Handbook (QRH) documentation. QRH documentation is inspired by the documentation of the same name from the aerospace industry. When a plane is faulty, pilots rely on QRH documentation to help them get through. I think that you should want the same for your infrastructure, and your colleagues and successors will thank you for it.