4 ms·

"We need engineers to not only feel that writing docs is their responsibility, but also to feel motivated to keep the quality of their docs high, and regularly

"We need engineers to not only feel that writing docs is their responsibility, but also to feel motivated to keep the quality of their docs high, and regularly maintain them." --- Can you share any specifics here? We're opening up tools, pulling notes from Jira, but the developer's docs still suck. There is rarely any meat to it, forcing us to become investigative journalists rather than tech editors.

nathancahill 11y ago
Write the documentation alongside the code it documents?
- jenncarlos 11y ago
  That's happening already. To be more specific, any ideas on getting developers engaged in creating "quality" docs? They don't really care about them right now, its just a necessary administrative step on the path to commit.
  - achamayou 11y ago
    When developers happen to be doing user support on the mailing list/forum/whatever you use, the importance of writing quality technical doc becomes more readily apparent to them. The volume of questions diminishes as the doc improves, they become more interesting, and you can get the simple ones out of the way by sending a link without remorse because you know it does contain exactly what the user was looking for. Of course it takes a little while for this to really engage, you'll need to kick a few people in the bottom to get past the initial investment, but in my experience it definitely works.
  - dandelany 11y ago
    Start enforcing. Make PR's required for all new code, and reject PR's which aren't well-documented. Most developers can write good docs, they (we) just tend not to, until docs are treated as a primary priority by the rest of the team.
    - TheOtherHobbes 11y ago
      There will be mutinous grumbling. But yes - this. Good docs are in everyone's interest. It's hard enough for insiders to maintain code that isn't documented properly. Worse, it's nearly impossible for outsiders to come in and make changes later - at least not without a lot of wasted time.
- gavinpc 11y ago
  It's called "literate programming." I'm embarrassed of the state of this thing, but I think I'd be remiss if I didn't link to https://willshake.net/about https://willshake.net/about It's a graph of a system based (almost) entirely on documents. The documents create the documents. The documents create the graph. And of course, the documents contain the code. I can't make enough disclaimers about how rough the documents are, and even the graph is starting to collapse under its own weight. But I think it gets the idea across. If I've learned one thing, it's that this style of programming---where you're forced to document as you go---is extremely work-intensive.
epc 11y ago
Have you considered hiring a technical writer? I don't mean a mediocre programmer who can write, I mean an excellent writer who excels at interviewing programmers, who can comprehend source code, and most of all is trained to be a writer?

nathancahill 11y ago

Write the documentation alongside the code it documents?

jenncarlos 11y ago
That's happening already. To be more specific, any ideas on getting developers engaged in creating "quality" docs? They don't really care about them right now, its just a necessary administrative step on the path to commit.
- achamayou 11y ago
  When developers happen to be doing user support on the mailing list/forum/whatever you use, the importance of writing quality technical doc becomes more readily apparent to them. The volume of questions diminishes as the doc improves, they become more interesting, and you can get the simple ones out of the way by sending a link without remorse because you know it does contain exactly what the user was looking for. Of course it takes a little while for this to really engage, you'll need to kick a few people in the bottom to get past the initial investment, but in my experience it definitely works.
- dandelany 11y ago
  Start enforcing. Make PR's required for all new code, and reject PR's which aren't well-documented. Most developers can write good docs, they (we) just tend not to, until docs are treated as a primary priority by the rest of the team.
  - TheOtherHobbes 11y ago
    There will be mutinous grumbling. But yes - this. Good docs are in everyone's interest. It's hard enough for insiders to maintain code that isn't documented properly. Worse, it's nearly impossible for outsiders to come in and make changes later - at least not without a lot of wasted time.
gavinpc 11y ago
It's called "literate programming." I'm embarrassed of the state of this thing, but I think I'd be remiss if I didn't link to https://willshake.net/about https://willshake.net/about It's a graph of a system based (almost) entirely on documents. The documents create the documents. The documents create the graph. And of course, the documents contain the code. I can't make enough disclaimers about how rough the documents are, and even the graph is starting to collapse under its own weight. But I think it gets the idea across. If I've learned one thing, it's that this style of programming---where you're forced to document as you go---is extremely work-intensive.

epc 11y ago

Have you considered hiring a technical writer? I don't mean a mediocre programmer who can write, I mean an excellent writer who excels at interviewing programmers, who can comprehend source code, and most of all is trained to be a writer?