I’ve been trying to be better about documenting in-house game dev processes, especially technical art workflows. They tend to contain many, many discrete steps between different programs and are very easy to forget. As the company grows I find documentation becoming more and more valuable.
Trouble is, so far I’ve been just making random Google documents for these processes. This… is not ideal.
- Over-reliance on Google
- Terrible formatting / no interlinking documents
- More or less non-portable
- People forget to read them, or have no idea documentation even exists
I think I’d like to try my hand at building a website to handle the documentation. There are a number of services I could use of course, but generally I’d like to avoid anything that requires a sign-up for rug-pull reasons. Let’s see what we got.
- Just use Hugo bro
- Yeah, theoretically, Hugo would work just fine. Markdown is an excellent way to create pages, and I could build functionality into the site myself. Users could make and edit .md files and submit them using P4, which we already use for Unreal.
- First problem I see is the static nature of Hugo. If a user submits a new .md file, who is gonna build the site? I could go all the way and set up some sort of auto build solutions. Jenkins, or whatever? Gets a bit complicated.
- Is there a dynamic version of Hugo? You know, something that auto updates? Hmm.
- Ok, the term is “Continuous Deployment”, essentially building and deploying the site whenever a Git hook is triggered. https://www.devonmorris.dev/posts/hugo-cd/#fn:1 Looks pretty straight forward - could this work with P4?
- Getting a vps to read P4 events could be way out of scope… or maybe not so bad. -Ok, uh, apparently there is a first party p4 - git connector???
- Technically, the docs could be 100% local lol.
UPDATE: OK, revisiting this after getting whitelotusinteractive.com online and cutting my teeth on Hugo. We could host on github and deploying on cloudflare is free and fast, and should be able to setup a subdomain easily. I don’t know if I can password protect it (could with Pangolin).
Authoring
- Hugo is a bit complicated and relies on git / github, requiring an account per editor.
- P4 git connector is too confusing / flimsy. In theory it would work great for keeping things easy but man that would be rough to setup, and risk fucking up our production.
- It looks like it would be possible to sync with Google Drive, but it looks fairly complicated. I also kinda want to start moving away from using drive (this docs page is part of that!)
- Any dynamic solution requires authentication, which is out of scope.
- I have this problem with the WLI blog as well.
- I could relatively simply convert google docs to .md and manually post them myself.
- Ohhhh you can edit directly on github.com! That may be simple enough! Still need a login but that is doable. Wouldn’t support adding images. Hmm. I may stick with github and eat the fact that for now I’ll be the only contributor. I think 99% of the docs written so far are from me anyways.
Is there a nice theme to use? I probably should try that so I can learn more.
- https://www.docsy.dev This is nice but probably a bit overkill. I also would prefer to stick with bulma vs bootstrap
Actual features I need:
- Side bar categories / articles menu
- Something line Content Authoring -> VAT, Vertex Paint ETC
- Prob don’t need the right side “on this page” view, but would be cool
- Hugo has some sort of menu code built in, learn that
- Link to view page source / edit link on github
- Breadcrumb at top of page
- index pages for categories (I think this is built in)
- Bulma “Alerts” shortcode would be nice I don’t think I care about taxonomy yet, though it might be nice to learn Don’t think I need search
Yeah I think I’ll roll my own, once again. Perhaps I’ll start this on the linux lappy, if that works.