post: net-doc

_posts/2024-10-01-net-doc.md

@@ -0,0 +1,55 @@
+---
+title: Net-Doc
+lead: Highly opinionateable documentation
+date: 2024-10-01
+tags:
+ - net-doc
+---
+For the past 8 months I've been working on a documentation system for us to store everything we might need on our network. Especially given that _"network"_ in a secondary school means everything from the Hyper-V cluster down to the access control units for the motorised gates at the front of school. 
+
+Documentation is a really important part of the network. I had little to none when I started at my current school and even with my best efforts I found that when our new engineer started I just didn't have the documentation needed to get them up to speed without me to answer lots of questions. So it came time to make a proper system and spend the time writing everything down. 
+
+I first started this project thinking I'd find it required more time than I could give it, but I'm almost surprised to say that today I released version 1.0.0, which represents the first stable release! There is still work to do and plenty of _issues_ placed against the version 1.1 milestone but right now it's working for us and getting better with every commit.
+
+We had tried a few systems before I decided to try building my own. Originally we used a shared OneNote notebook, which has the same flaw to me as a wiki, a lot of copying the same content around so we can make all the "VLAN" documentation look the same. Some of the systems I looked at seemed to either tie you into their structure, or where a wiki in a different skin.
+
+## What is Net-Doc?
+
+So what is Net-Doc? Net-Doc is a documentation system that allows you to build out the structure of your documentation your way. It gives very little out of the gate which allows 2 instances to vastly different. We for example have our "main" network documentation in one container and then another one which is the Duke of Edinbrugh kit list.
+
+Data is split into `Assets`, which are a collection of `Fields`. An `Entry` is an instance of an `Asset` which stores `Values` for the `Fields`. Some of the SQL queries are monsters, finding values only for entries that you have permission to read causes an interesting build up of conditions.
+
+There is then a "simple" markdown `document` store, which can feed into a `process` list. 
+
+Finally there is a `Password` system that stores passwords and user account details using reversible encryption. The keys for which are set in environment variables.
+
+All of these display their relationships and revisions, for example from our core switch entry.
+
+![Entry Links](/assets/2024/10/net-doc/entry-links.png)
+
+It has a link to the _Backups_ VLAN, as it is mentioned in the notes field for that VLAN. The link to the _Server Room_ network cab comes from a relation on the cabinet that lists all the switches in the cab. We then have a link to the password for the switch.
+
+There is then the revision history for the entry. From here we can go back to any point in the past for the entry.
+
+Our asset list has become quite big:
+
+![Asset List](/assets/2024/10/net-doc/asset-list.png)
+
+We've found it invaluable being able to build the assets as we need. We've even found that we've been replacing some fields with whole assets, getting ready to add sub-assets as a future feature.
+
+## How is Net-Doc?
+
+Net-Doc is built using [Remix](https://remix.run/) and [Prisma](https://www.prisma.io/) which have both been amazing to work with. The database backend is an [SQLite](https://www.sqlite.org/) database which really suits this use-case.
+
+There is quite a few packages included in Net-Doc that can all be found in the [package.json](https://github.com/Longridge-High-School/net-doc/blob/main/package.json).
+
+## What Next?
+
+We aren't done with Net-Doc, not by a long way. But today's release gets us a stable base to build from, and ultimately if we stopped development today it would function no problem for anyone taking over the network.
+
+All the enchancement ideas are listed on the GitHub issue tracker, so you can keep track of how was are going.
+
+## Links
+
+ - [GitHub](https://github.com/Longridge-High-School/net-doc)
+ - [Docs](https://longridge-high-school.github.io/net-doc/)