3 ms·

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.

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.