> when I hear "document on how to update something" I hear "untested set of manual steps" Why "untested" and why "manual"? I mentioned "detail" and "rigor" mo

> when I hear "document on how to update something" I hear "untested set of manual steps" Why "untested" and why "manual"? I mentioned "detail" and "rigor" more than once and that it's possible to take it and feed it into a machine that will "perform those steps automatically". I don't think kernel+shell are all that timeless of an interface to write to. They only barely pass for being portable in the here and now. (Oilshell's existence as a project is a testament to that. Its breadth and the depth of the pitfalls it has to avoid is another one.) Most of the time portability is an illusion that comes from most people around a given project being part of the same technological subculture, so they happen to use a common implementation. When you stray outside of that is when you run into breakage that no one is otherwise aware of. See also <https://pointersgonewild.com/2019/11/02/they-might-never-tell-you-its-broken/ https://pointersgonewild.com/2019/11/02/they-might-never-tel...>. > I don't quite understand what you are getting at so I think you must have a much different use case [...] It seems like you might be talking more about a blog that lots of people are editing? Nope, the use cases we're talking about are the same. I don't know where the lots of people editing parts comes in. What I'm talking about is conceptually very simple (maybe too simple, leading to an assumption that there's a lot more to it). It's a document that describes in detail, just like any other tech spec, precisely how to process a given input and turn it into a directory of static resources that you are used to dealing with, i.e., the output of a static site generator. The only difference between it and other specs is that in this document you specify things with enough rigor that you can effectively "execute" the specification itself. I've heard Rob Pike say in a few talks that some of the Golang backends come from a tool Ken wrote where they can feed in PDF manuals from microprocessor vendors and get a working Go assembler out of them, but I'm not intimately familiar with that tool. See also <http://www.moserware.com/2008/04/towards-moores-law-software-part-3-of-3.html http://www.moserware.com/2008/04/towards-moores-law-software...> where some RFC-style diagrams constitute a part of the implementation of a working TCP/IP stack. > If you have an example then that would help. I might do a short (? I'd hope) screencast next weekend if you're interested in providing some feedback. Asynchronously and pre-recorded, not live. My first assumption is that when you see what this is all about, then you're going to be pissed off. Based on your description of your current setup, though, that impression may not be accurate. > Apps are the things that rot. This is where my comments about "predilection for certain systems and ways of working" and how "we've missed the obvious and have been doing it all wrong" come from. In trying to solve these problems, there's way too much emphasis on apps, CI configurations, or whatever mindtrap is ensnaring people at the moment. The "obvious" approach I refer to is first adopting a mindset where it's an imperative to include a functional specification as described. I.e., add it to the set of things that you intend to publish on your site. Once you do this, it's hard not to notice that there's now an overlap between your data and the "app" you're using to publish it. So the second thing to do is to eliminate the part that's most susceptible to rot.