Hi! I had wrote this as a reddit comment a few years ago - but here it is again on this site.
Hi all! I was the documentation czar at an MSP (Guardian Solutions) utilizing The Competitor That Should Not Be Named - and then moved to Hudu a few years ago - where I've used and set it up for now multiple companies. Love it (mostly haha!).
Some helpful tips I've collected over the years for using Hudu, but more generally, any documentation system.
Start with the critical details. You can (and should!) fill in the rest later. Screenshots/images/formatting is important - but don't let documentation get daunting - start with the most critical things! Hire a documentation czar like me - to go back after the fact, format and fill in critical details.
Use the Diataxis Framework: https://diataxis.fr/. We do kind of like a modified version of this - which I'll list out below.
Automate as much as possible. One of the things I like the most about Hudu is that it's easy to get a lot of the reference documentation updated automatically. We have a ton of powershell scripts we use (i'll clean up and post) - but we also started using the Hudu N8N Node - which might replace some of our scripts going forward. One of the things we do as a company which I think is really cool is we have a whiteboard of Easy Automations we write down as a team - anytime we are doing the same thing over and over. then, we script it out.
Create KB templates like they are going out of style: We have an entire suite of KB templates that we enforce the usage of. We don't allow KB articles that haven't been created by a template.
Create a template for Quick Notes. Things like Key Contacts, Hours of Operation all go here.
Create naming conventions for...everything. I plucked this years ago from some site - but we've been using it ever since. We have a similar structure for processes. Flowcharts for everything. Stick them in the root KB folder so they are easy to find.
Don't use inches? For the rack storage tool - you can change inches to centimeters with Hudu Admin > General > Default System of Measurement
Hudu uses the full FontAwesome PRO Library. If you are looking to use custom icons - you can add them by the name when editing an asset layout. Let's you customize the design of Hudu a lot more. Pick better icons lol.
JUST got this off Discord last week (thanks leuit). A better dark mode theme (paste into Hudu Admin > Design). Warning - doesn't work if your team uses light mode.
/* Variables */
/* Default theme (Light Mode) */
:root {
--article-text-primary: #0a0a0a;
--article-text-secondary: #363636;
--line-height: 1.4em;
--spacing-unit: 1em;
--dark-d0: #bbbbbb;
--dark-d1: #d5d5d5;
--dark-d2: #e6e6e6;
--dark-d3: #efefef;
--dark-d4: #fafafa;
--theme-tone: white;
--app-text-primary: #0a0a0a;
--app-text-secondary: #3d3d3d;
--code-neutral: #4d4d4d;
--dark-border: #bababa;
--border-style-min: 1px solid var(--dark-border);
--border-style-alt: 1px solid #bababa;
--codeblock-header-height: 2em;
}
/* Dark Mode theme (when body has 'dark-portal' class) */
body.dark-portal {
--article-text-primary: #e0e0e0;
--article-text-secondary: #a3a3a3;
--dark-d0: #444444;
--dark-d1: #2a2a2a;
--dark-d2: #1b1b1b;
--dark-d3: #131313;
--dark-d4: #0a0a0a;
--theme-tone: black;
--app-text-primary: #fafafa;
--app-text-secondary: #cccccc;
--code-neutral: #bdbdbd;
--dark-border: #353535;
--border-style-min: 1px solid var(--dark-border);
--border-style-alt: 1px solid #4c4c4c;
}
/* latin */
@font-face {
font-family: 'JetBrains Mono';
font-style: normal;
font-weight: 400;
src: url(https://fonts.gstatic.com/s/jetbrainsmono/v20/tDbY2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKxTOlOV.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}
/* Inline and block code */
p > code, li > code {
background: var(--theme-tone);
white-space: nowrap;
word-wrap: break-word;
box-decoration-break: clone;
padding: 0.1rem 0.2rem;
border-radius: 0.2rem;
outline: var(--border-style-alt);
color: var(--article-text-secondary);
font-family: "JetBrains Mono", monospace;
font-size: 0.8em;
margin: 0 0.2rem;
}
li > div.code-toolbar:first-of-type, li > p.callout {
margin-top: var(--spacing-unit) !important;
}
div.code-toolbar {
display: grid;
margin-bottom: 1em;
border: var(--border-style-min);
}
div.code-toolbar > div.toolbar {
opacity: 1;
left: 0;
top: 0;
width: 100%;
height: auto;
grid-row: 1;
padding: 0.5rem 1rem;
display: flex;
position: relative;
flex-wrap: wrap;
align-items: baseline;
background: var(--dark-d3);
border-bottom: var(--border-style-min);
}
div.code-toolbar > pre[class*=language-] {
grid-row: 2;
background: var(--dark-d2);
padding: 1rem;
margin: 0;
}
div.code-toolbar > .toolbar > .toolbar-item {
color: var(--article-text-primary);
}
div.code-toolbar > .toolbar > .toolbar-item:first-of-type {
margin-right: auto;
}
div.code-toolbar > .toolbar > .toolbar-item > span {
user-select: none;
background: none;
box-shadow: none;
color: var(--article-text-secondary);
text-transform: lowercase;
font-family: 'JetBrains Mono', monospace;
padding: 0;
}
div.code-toolbar > .toolbar > .toolbar-item > span:hover {
color: var(--article-text-secondary);
}
div.code-toolbar > .toolbar > .toolbar-item > button {
display: inline-block;
box-shadow: none;
border: none;
background: none;
padding: 0.1em 0.2em 0.3em;
color: var(--article-text-secondary);
}
div.code-toolbar > .toolbar > .toolbar-item > button > span::before {
background: none;
font-family: "Font Awesome 5 Pro";
font-weight: 400;
color: inherit;
padding-right: 0.4em;
}
div.code-toolbar > .toolbar > .toolbar-item > button[data-copy-state=copy] > span::before {
content: "\f0c5";
}
div.code-toolbar > .toolbar > .toolbar-item > button[data-copy-state=copy-success] > span::before {
content: "\f00c";
}
code[class*=language-], pre[class*=language-] {
text-shadow: none;
font-family: 'JetBrains Mono', Consolas, monospace;
line-height: 1.2rem;
font-size: 13px;
color: var(--code-neutral);
}
.token.comment {
color: #85c46c;
}
.token.namespace {
color: #c191ff;
opacity: 1;
}
.token.boolean {
color: #ce8c6b;
}
.token.variable {
color: var(--code-neutral);
}
.token.function {
color: #39cc9b;
}
.token.keyword {
color: #6c95eb;
}
.token.operator {
color: var(--code-neutral);
}
.token.punctuation {
color: var(--code-neutral);
opacity: 1;
}
.token.string {
color: #c9a26d;
}
.token.string > .function {
color: var(--code-neutral);
}
.token.string > .boolean {
color: #66c3cc;
}
.token.string > .variable {
color: var(--code-neutral);
}
Week doesn't start on Sunday? Change this in the same place - Hudu Admin > General.
********************
I had mentioned we use a modified form of Diataxis - here is what we do:
Process Documentation
Use these to help employees accomplish a task
Name them How to Do X…Be specific.
Use good Process/Checklist software
Tutorials and Explanation
Use these to help employees learn
Describe concrete. Not abstract.
Use good KB software.
Reference Documentation (Change Management)
Use this to describe the environment. TO THE POINT.
Accuracy. Try and automate as much as possible!
Use a good CMDB software