During my long IT voyages, a realization struck me. It struck me just as I determined that the text in front of me is a part of a manual. This was the text I was meant to send to our latest frontend person.
A realization that I could save big time if I just compose my documentation out of my notes sent to co-workers, configuration files, everything.
That manual on how to update the frontend? This piece of text clearly belongs in the documentation part on the topic of frontend. This certificate file that I’m sending to that next guy? It belongs in the folder called documentation. Maybe not all the files will belong there (for example private keys) but most of them definitely will apply.
Imagine if your team members, instead of asking you to send them some files to replace in your newest environment, would find them on an online tool with a note that you’re sent them yesterday to your brand new colleague! It also replaced documentation-as-a-git-repo’s distinct lack of context with the best context – I sent that file to a guy who’s been bugging me about JDBC not working.
I say our documentations be composed of a paper-mache from the messages we just sent to our co-workers. The CTO will be impressed. The CEO will be impressed. That best-buying client of yours? He’ll be impressed as well.
Recently I very much appreciate the tool of dbdiagram. It tends to build ERD diagrams which are share-able via URLs for others to read or modify (premium option). I know that other projects, such as Figma, are also shareable by URLs. So that gives you plenty of space to host and tame such shadow IT.
This tool would give you an excuse to not deliver documentation for the end user, but to provide a living working map of a project to people who are developer’s (or have their skills) with all the configuration files and passwords requested! To treat the documentation not as a necessary evil that has to be understood by the end user, but as a living working repository. If you can afford it now, make your documentation into a git repo and add all of users ability to add things in peace, while you wait for chad and the needed extra added context.
Yeah, rethink what documentation is for. Writing PDFs for customers is so out-dated that it even isn’t funny. The documentation needs to be the body of knowledge of what you’re doing development-wise. This way, maintaining it will prove to be both necessary and fun!
So you no longer have an excuse not to attach documentation to your client’s new pet project! Many times over the price for producing documentation lead to it’s quick and strategic demise. I’m myself a poor copy-paste worker, instead preferring to upload a thick content of a manual book in to my head and then apply it there, as it all starts making sense). I work daily with projects like these, and they are in dire need of making documentation. There’s the source for the thought about improving (or at least making) documentation.
To this end, me and my colleagues at SMOK sp. z o. o. have joined project to develop such a solution. The colleagues at MTU Aero Engines Polska sp. z o. o. are still considering.
Development efforts are held at https://git.dms-serwis.com.pl/chad/chad . Feel free to join in, just type a mail at the address of:
The tool will consist of a backend, where the documentation is stored, and a deployable plugin to multiple communicators in order to look for the content in your messages. It will use the syntax of #chad<name_of_project>. And yes, it will require permissions to examine your entire inbox. Yes, it will read your entire inbox. But given that the code is publicly hosted and compiles and deploys via CI I do not see your risk very much. Note that you can host the tool as well, in which case you will be in control of who’s reading the messages.
Or maybe we overshot and such project exists this very instant? Tell me, please please, tell me now. I’m dying to listen to your opinion – you can just comment this article!
If you represent a development team that would like to give this method a go, you can contact me as well at the aforementioned e-mail address and be honored on this web page as well (if that’s what you desire).
Thank you and happy hacking!
Footnotes
I consulted the idea with some of my colleagues and found out that:
- The application should be performed more similarly to a plugin that a on-line message reader. Less surface for attacks, that’s for certain, although I’ve been a backend person for so long I nearly forgot these exist 😀
