7 ms·
Docs like code in basic terms
- DeborahWrites 1y agoMost 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.
- dcminter 1y agoThis seems well intentioned, but ... have you actually put this in front of a non-programmer and got them to try to create documentation using it? I suspect it's got more speedbumps left in it than you think.
- DeborahWrites 1y agoVery valid question. I have tested it a little! I wrote it because a less technical tech writer was asking me a ton of questions, and he found it helpful. I also got a non-technical marketing person to review it, and she said she was able to learn a lot from it (those are the two people I thank in the intro) It's obviously not going to get someone up and running: it's not a hands-on practical guide. But there are already quite a lot of those out there (for instance, most static site generators have acceptable getting started docs) The aim is to provide the missing conceptual info that's usually assumed by the creators of tools, but that not all tech writers have. Ideally, it should make them feel more comfortable following, say, an intro to git tutorial, because they have a bit more context/explanation backing them up.
- dcminter 1y agoGreat that you road-tested it! Real world data is always going to be higher quality than my drive-by opinion!
- bonzini 1y agoIn the early 2000s I was working in a webdev team where editors worked on the raw HTML (some with the help of Macromedia Dreamweaver, some simply with Notepad++) and pushed it to the httpd root via SFTP[1]. None of them had a developer background, I don't see why they wouldn't be able to do the same with Markdown and a pull request instead. [1] Nope, no version control :) though there were three separate domains for unstable/test/prod (test/prod shared the database too, unstable didn't).
- azdavis 1y agoI 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.
- kazinator 1y agodocs 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
- HumanOstrich 1y agoInteresting. Can you provide some source(s) for this rule?
- eru 1y agoEspecially since people like to play fast and loose with things like plurals in set phrases. See eg https://www.youtube.com/watch?v=AxlzkJAK1BM&t=22s https://www.youtube.com/watch?v=AxlzkJAK1BM&t=22s
- kazinator 1y agoThe source is the English language, do you speak it? :) Nouns that appear as modifiers in a compound noun are singular, and the need for a singular is so strong that English speakers invent singulars forms of plurale tantum words such as "jean jacket" rather than "jeans jacket". There are certain cases in which a plural modifier cannot be avoided, mainly because a plurale tantum doesn't singularize. We cannot singularize "goods" in "goods distribution network"; if we drop the "s", we get an adjective which completely changes the meaning. However, consider the word "supplies" which normally doesn't go to the singular word "supply" denoting one item. Yet in business we have "supply chain", not "supplies chain". There is a strong urge to eliminate plurals from the non-head position of a compound noun; the urge only loses in cases when a special kind of plural cannot be eliminated.
- simonw 1y ago
- 4b11b4 1y agoThis is.. about teaching people how to write text documents?
- goldfishgold 1y agoYes exactly. People who write text are not going to be excited about making saving their text such an extraordinarily complicated task, nor will they think it’s interesting in its own right.
- theletterf 1y agoThis is a dismissive comment, as is the parent. The post is about a well known software documentation paradigm.
- foobahhhhh 1y agoNot really. As a techie I prefer a CMS over say Jekyll.
- 4b11b4 1y agoI wasn't trying to be dismissive, only in line with the explicit call outs for simplicity from the author. I suppose I was trying to give the perspective of someone doesn't have a problem with authoring a markdown document for example... and bringing myself back to the reality that for most people authoring a document with any sort of formal (rigid, to be interpreted by machine) syntax is unfamiliar.
- PhilipRoman 1y agoBelieve it or not, when I started to learn programming I had no idea that "plain text" was a thing, since I had only been taught Word at school. So I think this is very valuable for many people who work in tech adjacent areas. Now I feel physical pain every time someone sends me documentation in Word format since I know there are at least five diverged versions floating around, with no easy way to compare them (Word diff is stuck in 20th century), full of embedded diagram PNGs that are impossible to update unless you were the author and inconsistent styling on top of that.
- foobahhhhh 1y agoI think from reading that, docs like code is roughly something like using Github and CI to manage docs rather than say WordPress or Confluence?
- ddulaney 1y agoYeah, exactly. If you're a developer, it can take a little bit to figure out that "docs like code" is a really strange concept to lots of non-developers. The idea of using the same tools to manage your docs as you manage your code only makes sense if you understand what tools you use to manage code! If you don't -- if your main experience with documentation tooling is Word, or maybe MadCap stuff -- that's a really huge leap to make.
- gsmethells 1y agoThis 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.
- airbreather 1y agoyeah, see my level 1 comment
- billfruit 1y agoThe terminology used is very confusing. There should be a better name for this than 'docs as code'.
- euroderf 1y ago"Docs' abode's the code"
- pella 1y agoOften the key is setting up an "executable documentation" environment. For example, "executable documentation" lets you run automated tests on your markdown files, keeping content fresh. some links: - https://github.com/MicrosoftDocs/executable-docs https://github.com/MicrosoftDocs/executable-docs - https://simonwillison.net/2018/Jul/28/documentation-unit-tests/ https://simonwillison.net/2018/Jul/28/documentation-unit-tes...
- westcoast49 1y agoSo this is WYSINWYG.
- kazinator 1y agoDeborah Writes ... ESL-level gibberish. I can't parse the title or the first sentence. Does she mean doc-like code?
- PhilipRoman 1y agohttps://www.writethedocs.org/guide/docs-as-code/ https://www.writethedocs.org/guide/docs-as-code/ Docs like code is a single term, maybe capitalization or dashes would help
- DeborahWrites 1y agoCapitalization would probably be a good idea, based on the comments here! Thanks!
- theletterf 1y agoThis comment goes against the spirit of respect that should reign on HN. Please contribute only if you've anything remotely interesting to say -- thank you!
- keybored 1y agoSkimming the text it seems okay. Relatively simple sentences (simple sentences are not necessarily good, depends on the complexity of the subject). A string of simple statements are used to continue the narrative. More complex sentences are built up with a few colons (should be semicolons) and a stringing together of commas that I personally will never get used to.
- branko_d 1y agoSummary: 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.
- theletterf 1y agoThe post is for non-devs. :)
- lproven 1y ago> builds everything into a website No! This is not about websites. It's about building manuals. The result could be a book, an ePub, a PDF, or -- almost incidentally -- a website.
- branko_d 1y agoThe above was copy-pasted from the article.
- airbreather 1y agoThe concept works better for somewhat regulated environments, I have used it for functional safety. 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
- ChrisMarshallNY 1y agoI’ve been using Apple’s docc[0]. It mostly just means that I write my code docs the same way as I always have (Doxygen markdown style), but it has an additional “compile” step, that produces a build artifact that integrates into the Xcode Documentation engine. You can make a pretty rich experience, with things like images and videos, all linked directly to your code. 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. [0] https://www.swift.org/documentation/docc/ https://www.swift.org/documentation/docc/
- meindnoch 1y agoOh. I thought doctors liked code.
- 1dom 1y agoIt took me a read or 2 to really make sense of this. I can see the use and value of it. The thing that I found really confusing was seeing "Docs Like Code". I've never really heard it said that way, and seeing it written down with that capitalisation kept me thinking that I was reading a sales tutorial for some SaaS pipeline integration offering. It would have all clicked immediately to me if it was called "Docs as Code" and made a link to concepts like infrastructure as code, config as code or everything as code. I think one thing to consider mentioning if you're targeting this at non-devs, Docs as Code is very much a case of: "to the person with a hammer, everything is a nail", meaning to the person without the hammer (non-devs), this is never going to seem like an easy, sensible or intuitive approach, even if it is comfortable for devs. Normal humans don't generally need to know about or do docs as code, because it doesn't make sense to them and is not efficient for them to produce. So if you find yourself in a position of having to explain this a lot to non devs, you should perhaps ask "is it easier for all the non devs to learn to be devs to update the docs? Or is it easier to change our docs platform to something usable by non-devs?"
- DeborahWrites 1y agoYeah, if your primary contributors aren't already comfortable with version control, you likely want to choose another toolset.
- subpixel 1y agoThis article is aimed at non-technical writers of documentation. A decade ago 'docs like code' was an exciting invitation to work alongside developers, adopt their practices, and get closer to how the sausage was being made. Today anything 'like code', but particularly prose, is right in the crosshairs of AI. While people who can leverage AI are a bigger threat to your job than AI alone, in this case those people are developers. When developers, who hold all of the context of software functionality in their head, can interact with an LLM to draft docs, test them against validation and style rules, and publish them, they just will.
- KolmogorovComp 1y agoTangential, but does anybody know a frontend more friendly than GitHub for non-technical persons to navigate through doc history? More like a wikipedia page history.
- DeborahWrites 1y agoSome knowledge base or wiki tools build this in, but I don't know of a friendlier alternative for text-based formats (markdown etc.) Would love to hear of it if you find one . . . I suspect it would need to be git or something similar under the hood though?
- VinLucero 1y agoWhat about Sphinx built documentation?