5 ms·

This is missing the point. The goal is "please write your documentation." What solution has the least friction around that for engineers? Right now, it's overw

This is missing the point. The goal is "please write your documentation." What solution has the least friction around that for engineers? Right now, it's overwhelmingly Markdown. It's not perfect, and often doesn't provide the features a technical writer or other content specialist might want, but it handles most use cases and is something developers are willing to write in. So please, write your documentation in whatever you feel like. As long as it gets written.

marcus_holmes 7y ago
Reading this and thinking of the dozen .md documents in my repo that are sooo badly out of date they're actually misleading. I apologise to anyone who ever has to read my documentation. I'm really, truly, sorry. I have excuses but no reasons.
- jenscow 7y ago
  Could you please share your excuses, so we can all use them? :)
- mpol 7y ago
  I do feel for you :) but at the same time I think Markdown, the tool, is not to blame for this. I write most of my documentation in Markdown or just plain text files. The reason is simple, I want the same focus that I had when writing the code. Doing a context switch from code/IDE to html/Web is a nightmare for me. If that would be mandatory for some reason, my documentation would suffer from more bitrot then it does now.
henriquez 7y ago
Right. The author kind of sets him up for this point by joking that LaTeX would be better, and then walking it back. Of course you could write docs in HTML with CSS if you wanted perfectly expressive syntax highlighting and context demarcation. And the opposite end of this would be arguing to use raw plaintext like an IETF specification. But really Markdown is ubiquitous and represents a usable compromise between being readable as plaintext while enabling the 'progressive enhancement' of being converted to HTML.
- treve 7y ago
  Fun fact: many IETF documents are written in Markdown now and converted to the other formats you are used to.
nixpulvis 7y ago
I agree 100% with your sentiment: > So please, write your documentation in whatever you feel like. As long as it gets written. Just so long as you remember who is supposed to be reading it, and ensure that they can. What language you use to structure it is more a question for you (and your team), and matters much less.
ozim 7y ago
Would up vote 5x ... Thing is "documentation nerds" are quite sparse and most people don't give a f. Going easiest way is the way to have documentation up to date. If someone wants to make it perfect so be it, let that person do it all. Then every change is left to such individual to be done and then guess what what happens when he is the person that has to do ALL the changes for documentation. Probably he won't have time to do more interesting things :)
dllthomas 7y ago
For me, the biggest source of friction when I sit down to write documentation is the knowledge that what I write will eventually wind up out of date and misleading - which can be worse than missing. What processes or tools do you know of to keep documentation up to date as code and environment change underneath it?
- njharman 7y ago
  Keeping docs and code as close together as possible. Certainly same repo. But for instance one of pythons greatest feature is docstrings. Which has encouraged documentation in the code. Other than that document in comments. And things like openapi and sphinx to generate docs from code. Low level docs such as foo() does x and raises error when y should be expressed as unit tests. External to code docs should be limited to things like deployment process.design docs (part of point of which is their history should be versioned not changed.
  - dllthomas 7y ago
    Proximity is a big help, for sure. Cross-references, ideally checked mechanically, can be helpful in making things proximate to multiple points. I very much agree with expressing assertions as tests. Doctest is an interesting point in the space, here. An idea I've had (and prototyped, but never quite got where I wanted) is a system where I can add references to tests as citations supporting claims in documentation, such that when the test fails the assertions it supports can be surfaced. Also, documentation that is frequently used is typically thereby checked against reality, and necessary updates found quickly. But much documentation won't be sufficiently frequently used to rely on that. There are many things that help. I'm always looking for more. Thanks for your input :)
- afarrell 7y ago
  Here is my proposal for any sort of docs that don't live right alongside the code. I have yet to put this into practice. There are 4 states for any page: - Maintained: "We are maintain this and aim to keep up to date. Message #slack-channel with any questions." - Stale: "Oops... we didn't." - News: "This represents our current thinking as of 23-Mar-2020" - Record: "This is a historical record of our intended system design, produced on 4-Aug-2018." When you write docs, be very clear whether you are writing a new report or something you intend to maintain. Reports become historical records after 1-3 months. Default to a report. Why? To keep small the number of docs which are "Maintained". Every maintained page is owned by a team of 2-10 people and the channel to contact them is visible on the page. Ideally, there would be a tool which attaches to every "Maintained" page and does 3 things. 1) Let the reader mark it as possibly stale or ask a question, then messages the page owners about that. Marks the page as stale within a week of non-response. 2) Mark the page as stale if the text isn't updated at least every 3 months. 3) Mark the page as stale if it doesn't get at least N page-views in 3 months. I'm serious about point #3. If a page is rarely-read by others, then the team which owns it is not pointing people to it or using it for training. If that is the case, then why should they spend time and attention to keep it up-to-date? Is it an emergency runbook? Well then either that info is important enough to walk through it periodically, or you should be honest with yourself that what that doc really says is, "This was the suggested runbook we came up with after a post-mortem 2 years ago. It might be very useful for understanding the system. Maybe it even still works."
stinos 7y ago
I don't think the author misses that particular point. It's just that the author's goals are obviously different and way beyond just having documentation apparently. I mean, quote: You should be able to hide all the definitions if you want or show only the definitions. You should be able to mark several code samples as doing the same thing in different languages. You should be able to generate the documentation with and without “TODO” sections, so you can share separate versions internally and externally When I read that I was like 'wtf is this about'. For someone who barely has any documentation at all usually (me) this seems next level. But thinking of it this actually makes sense and I totally understand that if you're at the point where you want to apply those things you likely have a ton of ducumentation and perhaps don't need being pointed out that the main goal is writing it and you're most likely right in saying that markdwon is not the correct tool for that job.

marcus_holmes 7y ago

Reading this and thinking of the dozen .md documents in my repo that are sooo badly out of date they're actually misleading. I apologise to anyone who ever has to read my documentation. I'm really, truly, sorry. I have excuses but no reasons.

jenscow 7y ago
Could you please share your excuses, so we can all use them? :)
mpol 7y ago
I do feel for you :) but at the same time I think Markdown, the tool, is not to blame for this. I write most of my documentation in Markdown or just plain text files. The reason is simple, I want the same focus that I had when writing the code. Doing a context switch from code/IDE to html/Web is a nightmare for me. If that would be mandatory for some reason, my documentation would suffer from more bitrot then it does now.

henriquez 7y ago

Right. The author kind of sets him up for this point by joking that LaTeX would be better, and then walking it back. Of course you could write docs in HTML with CSS if you wanted perfectly expressive syntax highlighting and context demarcation. And the opposite end of this would be arguing to use raw plaintext like an IETF specification. But really Markdown is ubiquitous and represents a usable compromise between being readable as plaintext while enabling the 'progressive enhancement' of being converted to HTML.

treve 7y ago
Fun fact: many IETF documents are written in Markdown now and converted to the other formats you are used to.

nixpulvis 7y ago

I agree 100% with your sentiment: > So please, write your documentation in whatever you feel like. As long as it gets written. Just so long as you remember who is supposed to be reading it, and ensure that they can. What language you use to structure it is more a question for you (and your team), and matters much less.

ozim 7y ago

Would up vote 5x ... Thing is "documentation nerds" are quite sparse and most people don't give a f. Going easiest way is the way to have documentation up to date. If someone wants to make it perfect so be it, let that person do it all. Then every change is left to such individual to be done and then guess what what happens when he is the person that has to do ALL the changes for documentation. Probably he won't have time to do more interesting things :)

dllthomas 7y ago

For me, the biggest source of friction when I sit down to write documentation is the knowledge that what I write will eventually wind up out of date and misleading - which can be worse than missing. What processes or tools do you know of to keep documentation up to date as code and environment change underneath it?

njharman 7y ago
Keeping docs and code as close together as possible. Certainly same repo. But for instance one of pythons greatest feature is docstrings. Which has encouraged documentation in the code. Other than that document in comments. And things like openapi and sphinx to generate docs from code. Low level docs such as foo() does x and raises error when y should be expressed as unit tests. External to code docs should be limited to things like deployment process.design docs (part of point of which is their history should be versioned not changed.
- dllthomas 7y ago
  Proximity is a big help, for sure. Cross-references, ideally checked mechanically, can be helpful in making things proximate to multiple points. I very much agree with expressing assertions as tests. Doctest is an interesting point in the space, here. An idea I've had (and prototyped, but never quite got where I wanted) is a system where I can add references to tests as citations supporting claims in documentation, such that when the test fails the assertions it supports can be surfaced. Also, documentation that is frequently used is typically thereby checked against reality, and necessary updates found quickly. But much documentation won't be sufficiently frequently used to rely on that. There are many things that help. I'm always looking for more. Thanks for your input :)
afarrell 7y ago
Here is my proposal for any sort of docs that don't live right alongside the code. I have yet to put this into practice. There are 4 states for any page: - Maintained: "We are maintain this and aim to keep up to date. Message #slack-channel with any questions." - Stale: "Oops... we didn't." - News: "This represents our current thinking as of 23-Mar-2020" - Record: "This is a historical record of our intended system design, produced on 4-Aug-2018." When you write docs, be very clear whether you are writing a new report or something you intend to maintain. Reports become historical records after 1-3 months. Default to a report. Why? To keep small the number of docs which are "Maintained". Every maintained page is owned by a team of 2-10 people and the channel to contact them is visible on the page. Ideally, there would be a tool which attaches to every "Maintained" page and does 3 things. 1) Let the reader mark it as possibly stale or ask a question, then messages the page owners about that. Marks the page as stale within a week of non-response. 2) Mark the page as stale if the text isn't updated at least every 3 months. 3) Mark the page as stale if it doesn't get at least N page-views in 3 months. I'm serious about point #3. If a page is rarely-read by others, then the team which owns it is not pointing people to it or using it for training. If that is the case, then why should they spend time and attention to keep it up-to-date? Is it an emergency runbook? Well then either that info is important enough to walk through it periodically, or you should be honest with yourself that what that doc really says is, "This was the suggested runbook we came up with after a post-mortem 2 years ago. It might be very useful for understanding the system. Maybe it even still works."

stinos 7y ago

I don't think the author misses that particular point. It's just that the author's goals are obviously different and way beyond just having documentation apparently. I mean, quote: You should be able to hide all the definitions if you want or show only the definitions. You should be able to mark several code samples as doing the same thing in different languages. You should be able to generate the documentation with and without “TODO” sections, so you can share separate versions internally and externally When I read that I was like 'wtf is this about'. For someone who barely has any documentation at all usually (me) this seems next level. But thinking of it this actually makes sense and I totally understand that if you're at the point where you want to apply those things you likely have a ton of ducumentation and perhaps don't need being pointed out that the main goal is writing it and you're most likely right in saying that markdwon is not the correct tool for that job.