21–30 of 61 posts
Earlier quoted context omitted.
docs is plural. You can't have a plural in a noun phrase, other than in he head position. For instance OK, no plurals: law school entrance test OK, head plural: law school entrance tests ?? non-head plural: law school entrances test
Interesting. Can you provide some source(s) for this rule?
I didn’t realize that “docs like code” was a noun phrase and was trying to figure out how docs can be liking code that is in basic terms.
docs is plural. You can't have a plural in a noun phrase, other than in he head position. For instance OK, no plurals: law school entrance test OK, head plural: law school entrance tests ?? non-head plural: law school entrances test
1. Write some docs in a text editor.
2. Using git, send your new docs to GitHub.
3. Follow some steps on GitHub to finish adding your new docs to the site.
4. A process runs which takes your changes, builds everything into a website (using the static site generator), and deploys it to a server.
I didn’t realize that “docs like code” was a noun phrase and was trying to figure out how docs can be liking code that is in basic terms.
docs is plural. You can't have a plural in a noun phrase, other than in he head position. For instance OK, no plurals: law school entrance test OK, head plural: law school entrance tests ?? non-head plural: law school entrances test
This works amazingly well for regulated software markets such as medical devices that need a lot of review/approval and traceability. Markdown is much more AI and script-friendly yet still layman readable. The workflow is significantly faster than industry standard tools like Windchill which are like git with a 1985 GUI in front of it.
I didn’t realize that “docs like code” was a noun phrase and was trying to figure out how docs can be liking code that is in basic terms.
To me "Docs like code" conjures up documentation that looks like code, so I think something like "The basics of using programmers' tools to create documentation" would be clearer.
Earlier quoted context omitted.
docs is plural. You can't have a plural in a noun phrase, other than in he head position. For instance OK, no plurals: law school entrance test OK, head plural: law school entrance tests ?? non-head plural: law school entrances test
"Docs" is short for "documentation", not "documentations".
Most guides to docs like code, even the ones for non-devs, assume you have some developer knowledge: maybe you're already using version control, or you've encountered build pipelines before, or you're working alongside developers. This guide is for the people who read that paragraph and wished it came with a glossary. This is docs like code for people who don't know what git is and have never installed VS Code.
For industrial controller software, esp distributed systems, there is a precedent of the standard IEC 61499.
One of the key components is the concept of an "Executable Specification", which may sound like unachievable BS, but if you are mainly doing state based systems, can be achieved by using state machines and working within a certain methodology/Activity framework.
I even wrote my own desktop application in PyQt specifically to satisfy requirements of 61508/61511 and the local burner code AS3814. The combustion and process engineers used this to specify (and verify by simulation, all within the tool) the exact exhaustive and unambiguous behavior for the machines (burner systems). As well for every state and transition condition attach a narrative about why it was like it was, with references, diagrams, attachments of manuals and datasheets etc.
Once all was decided, press the button, makes code, makes a documentation specification and compendium, and gives a level of traceability that is suitable for SIL 3, better accuracy, the systems guy (programmer) did not have to be a combustion engineer as well, because usually the crappy narrative type spec is always inadequate.
For certain types of code, this is the way of the future, and for things like rail and other super critical safety functionality, allows easy translation for application of formal methods to verify no unreachable conditions etc etc etc.
I had many colleagues that were initially in disbelief of the complexity but certainty of arbitrary functionality that was able to be specified with various hierarchal structures of state machines, as an executable specification
Fairly cool, but it requires Xcode, to work properly. It doesn’t really have a decent “export” capability, for things like GitHub Pages. There’s a fairly awkward way prescribed by Apple, that is annoying AF, and breaks easily, so I don’t usually bother. I’ll use Jazzy Docs to produce the GH Pages output.
I would love it, if GitHub would parse docc artifacts for GH Pages, but it’s probably too much of a pain to do.