Docs like code in basic terms
deborahwrites.com
Docs like code in basic terms
1–10 of 61 posts
Re: Docs like code in basic terms
#2Most 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.
Re: Docs like code in basic terms
#3I 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.
Re: Docs like code in basic terms
#4This is.. about teaching people how to write text documents?
Re: Docs like code in basic terms
#5This is.. about teaching people how to write text documents?
Yes 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.
Re: Docs like code in basic terms
#6This is.. about teaching people how to write text documents?
Yes 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.
This is a dismissive comment, as is the parent. The post is about a well known software documentation paradigm.
Re: Docs like code in basic terms
#7I think from reading that, docs like code is roughly something like using Github and CI to manage docs rather than say WordPress or Confluence?
Re: Docs like code in basic terms
#8Earlier quoted context omitted.
Yes 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.
This is a dismissive comment, as is the parent. The post is about a well known software documentation paradigm.
Not really. As a techie I prefer a CMS over say Jekyll.
Re: Docs like code in basic terms
#9This 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.
Re: Docs like code in basic terms
#10Earlier quoted context omitted.
Yes 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.
This is a dismissive comment, as is the parent. The post is about a well known software documentation paradigm.
I 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.