Been using UNIX since the late 80s; Linux since the mid-90s; virtualization since the early 2000s and spent the past few years working in the cloud space.
Location
Alexandria, VA, USA
Education
B.S. Psychology from Pennsylvania State University
Actually, I write tons of documentation. It's kind of a necessity: I jump back and forth across projects within a given contract plus breaking across contracts. While I've got a freakish memory, if I don't at least write breadcrumbs for myself, it's back to the Googs I must go (sometimes finding my own articles).
For me, the most onerous problem is the layers of documentation and the available tools to write/maintain it in. Not only do I have the problem of "keep the dox in sync with the code", I then have the "meta" task of "dumb that documentation down". And the inevitable "we've got to push your stuff out to new audiences: please dumb the dox down some more". Keeping layers of documentation reflective of the current code-based reality is, at best, "a chore".
I strive for "obviousness" in everything that I write - be it code or documentation. In general, I try to make it so that if you have half a clue, you can figure out what's going on just by how things are named, how they're organized, how their exits are trapped/signalled ...and how the blocks they're in are commented. But most people are code-phobic and won't even look in the code to see if something smacks them in the face. My first layer of not-embedded-in-the-code documentation is typically READMEs kept in the code's project. Those tend to stay fairly in sync with the code ...but that's mostly self-discipline that sees to that.
I assume that, with my in-project documentation, I could probably set up triggers that send me "I see you updated tool X but the document that seems to reference it wasn't updated: is that correct" types of messages. Haven't really investigated because we generally don't get funding for the kind of for-fee tools that I could probably leverage for that.
As to the further-abstracted documentation - that are hosted away from the code (in RedMine, Confluence or whatever a given contract's preferred documentation-tool is) - it's beyond a pain to keep it all up to date. I know that everyone loves simplified markup languages ...but there seem to be enough SMLs that simply cutting-and-pasting from one documentation-system to another doesn't really work.
I mean, you can see this just in Dev.To if you've set up RSS-based publishing from your "real" blogs' location. Something that looks great on your preferred platform requires significant massaging to make look the same in Dev.To. And that assumes that Dev.To's Markdown (SML) flavor supports the same feature sets that your article source was written in.
I've tried tools like PanDoc to get around some of these problems, "Markdown is Markdown is Markdown" isn't quite true and you can get surprises when your auto-formatted code doesn't quite render the way you expected i to. While authoring languages like HTML (or even TeX/LaTeX) have steep learning curves (particularly if you want to get fancy with their extended feature-sets), they felt both a lot more reliably portable and controllable.
I wish I knew the solution to the problem. Also wish I could say it seems like things are getting better ...but the opposite feels to be true.
I've never been a part of an organization large enough to have these kinds of issues, but it definitely sounds like automating the docs process only gets more important at larger scales, while the very nature of the available tools severely hinders this. But it gets me thinking: do you think some of these problems would get better if the synchronization worked by pushing out the rendered markup rather than the SML itself? So, for example, having one system that that allows you to write in your preferred SML, and notifies other systems of changes by compiling that markup and just pushing out pure HTML?
Been using UNIX since the late 80s; Linux since the mid-90s; virtualization since the early 2000s and spent the past few years working in the cloud space.
Location
Alexandria, VA, USA
Education
B.S. Psychology from Pennsylvania State University
I really wish I knew what the answer was. When it comes to writing - be it code or dox - I really prefer "write it once" methods. And, while HTML is pretty well standardized and stable, the richer the use of that HTML/CSS, the harder it is for many SMLs to decompose it into something they can render.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Actually, I write tons of documentation. It's kind of a necessity: I jump back and forth across projects within a given contract plus breaking across contracts. While I've got a freakish memory, if I don't at least write breadcrumbs for myself, it's back to the Googs I must go (sometimes finding my own articles).
For me, the most onerous problem is the layers of documentation and the available tools to write/maintain it in. Not only do I have the problem of "keep the dox in sync with the code", I then have the "meta" task of "dumb that documentation down". And the inevitable "we've got to push your stuff out to new audiences: please dumb the dox down some more". Keeping layers of documentation reflective of the current code-based reality is, at best, "a chore".
I strive for "obviousness" in everything that I write - be it code or documentation. In general, I try to make it so that if you have half a clue, you can figure out what's going on just by how things are named, how they're organized, how their exits are trapped/signalled ...and how the blocks they're in are commented. But most people are code-phobic and won't even look in the code to see if something smacks them in the face. My first layer of not-embedded-in-the-code documentation is typically READMEs kept in the code's project. Those tend to stay fairly in sync with the code ...but that's mostly self-discipline that sees to that.
I assume that, with my in-project documentation, I could probably set up triggers that send me "I see you updated tool X but the document that seems to reference it wasn't updated: is that correct" types of messages. Haven't really investigated because we generally don't get funding for the kind of for-fee tools that I could probably leverage for that.
As to the further-abstracted documentation - that are hosted away from the code (in RedMine, Confluence or whatever a given contract's preferred documentation-tool is) - it's beyond a pain to keep it all up to date. I know that everyone loves simplified markup languages ...but there seem to be enough SMLs that simply cutting-and-pasting from one documentation-system to another doesn't really work.
I mean, you can see this just in Dev.To if you've set up RSS-based publishing from your "real" blogs' location. Something that looks great on your preferred platform requires significant massaging to make look the same in Dev.To. And that assumes that Dev.To's Markdown (SML) flavor supports the same feature sets that your article source was written in.
I've tried tools like PanDoc to get around some of these problems, "Markdown is Markdown is Markdown" isn't quite true and you can get surprises when your auto-formatted code doesn't quite render the way you expected i to. While authoring languages like HTML (or even TeX/LaTeX) have steep learning curves (particularly if you want to get fancy with their extended feature-sets), they felt both a lot more reliably portable and controllable.
I wish I knew the solution to the problem. Also wish I could say it seems like things are getting better ...but the opposite feels to be true.
I've never been a part of an organization large enough to have these kinds of issues, but it definitely sounds like automating the docs process only gets more important at larger scales, while the very nature of the available tools severely hinders this. But it gets me thinking: do you think some of these problems would get better if the synchronization worked by pushing out the rendered markup rather than the SML itself? So, for example, having one system that that allows you to write in your preferred SML, and notifies other systems of changes by compiling that markup and just pushing out pure HTML?
I really wish I knew what the answer was. When it comes to writing - be it code or dox - I really prefer "write it once" methods. And, while HTML is pretty well standardized and stable, the richer the use of that HTML/CSS, the harder it is for many SMLs to decompose it into something they can render.