7 ms·

"prefers working code over comprehensive documentation" does not mean "don't do documentation". Documentation is essential. How things work is an important thi

"prefers working code over comprehensive documentation" does not mean "don't do documentation". Documentation is essential. How things work is an important thing to document. Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date. It still has problems (What do you do when the code and the documentation disagree? Which is correct?), but they're not as severe as the problems that arise when there is no documentation at all. What is less useful is having comprehensive documentation for those things that are yet to exist. Writing a few hundred pages of specification and handing it over to the dev team is waterfall, and it is _this_ that the Agile manifesto signatories were interested in making clear. I'd fix it with strategic DDD - I'd develop at least a "ubiquitous language" (or a UL): I'd get others to work with me on having clear terminology and making sure that is used consistently both in user stories and in the code base. That's table stakes. I'd then event storm the contexts I'm working in and start to develop high level documentation. Even at this point relationships between systems emerge, and you get to draw circles around things and name them (domains, contexts), and the UL gets a bit better. At this point you can start to think about describing some of your services using the UL and the language of domains and contexts. By that point, people should start to click that this makes life easier - there is less confusion, and you're now all working together to get a shared understand of the design and the point of DDD is that the design and the code match. The first part (all 100+ pages of it), of the Millet and Tune book on DDD will pay you dividends here. If that doesn't work, look around for somewhere else to work that understands that software development is often a team sport and is committed to making that happen.

clumsysmurf 7y ago
Thanks for the thoughtful response, this is helpful. > Ideally it should be in version control and be generated from the code .. May I ask if you have suggestions for tooling to capture the high level documentation. We use javadoc a little, but it seems best for lower level reference. Also for diagrams, like sequence diagram and/or state machines, how do you capture this? Thanks.
- konstmonst 7y ago
  Use graphviz (dot tool for example) for state machines. It is a text format where you list state machine transitions and it generates a visual representation. Or better yet: generate your state machines from same format you would use to generate visual representation.
- PaulRobinson 7y ago
  Don't be afraid of building a product specification, and doing it in Markdown and auto-generating a mini-website out of it. Just build a product specification for how the product works (which is useful documentation), not how the product will work (which is waterfall). We're experimenting with this a little, and I'm getting into document-driven development a little: if the product spec is in markdown, why not create a pull request on it as part of your story/project planning that shows the changes that would happen as a consequence of your work. Once the story is done, you can merge the pull request, even. We're not quite there with this yet, but I'm optimistic. Putting design assets into your repo is also acceptable, and also paying time and attention to commit messages can be really, really helpful. I love this talk, for example: https://brightonruby.com/2018/a-branch-in-time-tekin-suleyman/ https://brightonruby.com/2018/a-branch-in-time-tekin-suleyma...
JohnBooty 7y ago
Documentation is essential. How things work is an important thing to document. Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date. My solution to this is old and fairly unpopular, but I stand by it: anything in the codebase that's not obvious to a new maintainer should have a brief, explanatory code comment. Generally, this falls into two categories. 1. Hacks/kludges to get around bugs in hardware, external services, or included libraries. These manifest in code as incomprehensible, ugly bits of code that are difficult to distinguish from code that is simply "sloppy" or uninformed. More importantly, they represent hard-won knowledge. It often takes many programmer-hours to discover that knowledge, and therefore many dollars. Why throw it away? (Tip: include the version of the dependency in the comment, ie) # work around bug in libfoo 2.3, see blahblahblah.com/issues/libfoo/48987 for info # should go away once we can upgrade to libfoo 3.. if error_code == 42 reset_buffer() ...so that future programmers (including you) can more easily judge whether the kludge is still needed in the future. 2. Business logic. This too is difficult/impossible to discern from looking at code. Often, one's git commit history is sufficient. But there are any number of scenarios where version control history can become divorced from the code, or require a fair bit of git/hg/svn/whatever spelunking to access. And this of course becomes increasingly onerous as a module grows. If there are 200 lines of code in a given module, it is a significant time investment to go git spelunking for the origins of all 200 lines of code. Some concise internal documentation in the form of code comments can save an order of magnitude or two of effort. It still has problems (What do you do when the code and the documentation disagree? Which is correct?), but they're not as severe as the problems that arise when there is no documentation at all. This is pretty easy to enforce at code review time, prior to merging. In the first place, only a true maniac would intentionally update # no sales tax in Kerplakistan on Mondays return nil if country_code==56 and day_of_week==1 ...without updating the associated comment. If they do neglect to update it, that's an easy catch at review time.
- irishsultan 7y ago
  While I still would add a comment about the why, your last bit of code probably should be written without magic constants. # Some countries have sales tax rules dependent on the day of the week return nil if country_code==KERPLAKISTAN and day_of_week==MONDAY The exact comment here could probably be more specific (e.g. where do you find these rules), but it also most likely shouldn't repeat the code (and the code should make clear what it represents).
mrmonkeyman 7y ago
I never understood why generated API docs are "documentation". That is source, trivial technical info which is easy to find in the source anyway. I never got documentation about the thought processes, the iterations, the design meeting, the considerations, etc. Which is way, way more important to understanding a system in context than knowing "convertLinear" takes 2 unsigned ints.
abdullahkhalids 7y ago
> Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date Interestingly, this has been a big point of discussion in the Dota 2 playerbase. Dota 2 is one of the most complex games ever created and it rapidly changes on the order of days or weeks. At one point, the in-game descriptions of spells were months or years out of date because they were being updated manually. After much hue and cry from the community, the developers finally made the tooltips get generated from the same code that determined the spells' effects. Things are a bit better now. There is still a quite a bit of ways to go though, in terms of generating documentation for all the other mechanics in the game, which are crucial for gaining competency in the game, but which are only available due to third-party community efforts (often via people reading the game's codebase to understand subtleties), instead of being available inside the game.
- roland35 7y ago
  This is a good example of a general rule of thumb I learned, if you need to do something once or twice do it by hand, but if you do something three or more times make it a function! Looks like Dota 2 updated their spells a few more than 3 times ;)
  - bcrosby95 7y ago
    I use this rule for introducing abstraction: don't do it unless you have at least 3 different use cases you're abstracting, and the test suite doesn't count.
- vharuck 7y ago
  It's surprising that wasn't being done in the first place. I used the Warcraft 3 map editor, and it was simple to include references to attribute values in an object's description. Don't know why the DotA2 team didn't port that feature over when moving to the new engine.
madeofpalk 7y ago
> Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date Not always - when you want to document the requirements (in whatever format), having them be separate from the code is often a plus. The code might implement the requirements incorrectly, so being able to recognise that is important. I find this very similar to writing tests that are separate from your implementation. In fact, Cucumber/BDD tests try to make product requirements executable to validate the software has been written correctly to meet the requirements.
somtum 7y ago
How does Millet and Tune's DDD book compare with Eric Evans? Are they both worth reading?
ptero 7y ago
> Documentation is essential. How things work is an important thing to document. I agree with this 100%. However, to be useful it needs to hit the right level of crudity. For most projects, a short (<10 pages) description of goals, design principles, architecture and an overview of interfaces is sufficient. It is best when this exists as a standalone document which is a required reading for any new developer. After this they can look at module descriptions, function docs, code, etc. and understand how to make sense of it and how to add their code without breaking general principles of the project. > Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date. With this, I have some beef. In my experience the best documentation is the one that complements the code. Usually this means a short description by a human that explains what this chunk of code does and assumptions or limitations (e.g., "tested only for points A and B in troposphere") and IME most useful information is not derivable automatically. Auto-generated docs are very useful, but cannot replace clean explanations written by a human. My 2c.
- roland35 7y ago
  I think there is room for this to be two documents if a project is large enough - one which resides inside source control which explains the design and how it works, and one which is external (sometimes managed by corporate level document control) which explains the "so what", including top level requirements and so forth. These could be just one document if the project is small enough.
- 0xffff2 7y ago
  I think there's a lot of ambiguity in the phrase "generated from the code". When I hear it, I think if docs generated from doc-comments embedded in the code, which hare clean explanations written by a human. They just have the advantage of being right next to the code, so they're a lot more likely to be updated when the code changes than an entirely external document. "Documentation" that is nothing more than the interface definitions in HTML for is worse than useless. I can get all of that from just reading the code.
collyw 7y ago
> Writing a few hundred pages of specification and handing it over to the dev team is waterfall, and it is _this_ that the Agile manifesto signatories were interested in making clear That doesn't sound too bad from a dev point of view, better than the opposite - half arsed specifications with no thought given to the important details. Though I can imagine a lot depends on what exactly you are trying to build.

clumsysmurf 7y ago

Thanks for the thoughtful response, this is helpful. > Ideally it should be in version control and be generated from the code .. May I ask if you have suggestions for tooling to capture the high level documentation. We use javadoc a little, but it seems best for lower level reference. Also for diagrams, like sequence diagram and/or state machines, how do you capture this? Thanks.

konstmonst 7y ago
Use graphviz (dot tool for example) for state machines. It is a text format where you list state machine transitions and it generates a visual representation. Or better yet: generate your state machines from same format you would use to generate visual representation.
PaulRobinson 7y ago
Don't be afraid of building a product specification, and doing it in Markdown and auto-generating a mini-website out of it. Just build a product specification for how the product works (which is useful documentation), not how the product will work (which is waterfall). We're experimenting with this a little, and I'm getting into document-driven development a little: if the product spec is in markdown, why not create a pull request on it as part of your story/project planning that shows the changes that would happen as a consequence of your work. Once the story is done, you can merge the pull request, even. We're not quite there with this yet, but I'm optimistic. Putting design assets into your repo is also acceptable, and also paying time and attention to commit messages can be really, really helpful. I love this talk, for example: https://brightonruby.com/2018/a-branch-in-time-tekin-suleyman/ https://brightonruby.com/2018/a-branch-in-time-tekin-suleyma...

JohnBooty 7y ago

Documentation is essential. How things work is an important thing to document. Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date. My solution to this is old and fairly unpopular, but I stand by it: anything in the codebase that's not obvious to a new maintainer should have a brief, explanatory code comment. Generally, this falls into two categories. 1. Hacks/kludges to get around bugs in hardware, external services, or included libraries. These manifest in code as incomprehensible, ugly bits of code that are difficult to distinguish from code that is simply "sloppy" or uninformed. More importantly, they represent hard-won knowledge. It often takes many programmer-hours to discover that knowledge, and therefore many dollars. Why throw it away? (Tip: include the version of the dependency in the comment, ie) # work around bug in libfoo 2.3, see blahblahblah.com/issues/libfoo/48987 for info # should go away once we can upgrade to libfoo 3.. if error_code == 42 reset_buffer() ...so that future programmers (including you) can more easily judge whether the kludge is still needed in the future. 2. Business logic. This too is difficult/impossible to discern from looking at code. Often, one's git commit history is sufficient. But there are any number of scenarios where version control history can become divorced from the code, or require a fair bit of git/hg/svn/whatever spelunking to access. And this of course becomes increasingly onerous as a module grows. If there are 200 lines of code in a given module, it is a significant time investment to go git spelunking for the origins of all 200 lines of code. Some concise internal documentation in the form of code comments can save an order of magnitude or two of effort. It still has problems (What do you do when the code and the documentation disagree? Which is correct?), but they're not as severe as the problems that arise when there is no documentation at all. This is pretty easy to enforce at code review time, prior to merging. In the first place, only a true maniac would intentionally update # no sales tax in Kerplakistan on Mondays return nil if country_code==56 and day_of_week==1 ...without updating the associated comment. If they do neglect to update it, that's an easy catch at review time.

irishsultan 7y ago
While I still would add a comment about the why, your last bit of code probably should be written without magic constants. # Some countries have sales tax rules dependent on the day of the week return nil if country_code==KERPLAKISTAN and day_of_week==MONDAY The exact comment here could probably be more specific (e.g. where do you find these rules), but it also most likely shouldn't repeat the code (and the code should make clear what it represents).

mrmonkeyman 7y ago

I never understood why generated API docs are "documentation". That is source, trivial technical info which is easy to find in the source anyway. I never got documentation about the thought processes, the iterations, the design meeting, the considerations, etc. Which is way, way more important to understanding a system in context than knowing "convertLinear" takes 2 unsigned ints.

abdullahkhalids 7y ago

> Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date Interestingly, this has been a big point of discussion in the Dota 2 playerbase. Dota 2 is one of the most complex games ever created and it rapidly changes on the order of days or weeks. At one point, the in-game descriptions of spells were months or years out of date because they were being updated manually. After much hue and cry from the community, the developers finally made the tooltips get generated from the same code that determined the spells' effects. Things are a bit better now. There is still a quite a bit of ways to go though, in terms of generating documentation for all the other mechanics in the game, which are crucial for gaining competency in the game, but which are only available due to third-party community efforts (often via people reading the game's codebase to understand subtleties), instead of being available inside the game.

roland35 7y ago
This is a good example of a general rule of thumb I learned, if you need to do something once or twice do it by hand, but if you do something three or more times make it a function! Looks like Dota 2 updated their spells a few more than 3 times ;)
- bcrosby95 7y ago
  I use this rule for introducing abstraction: don't do it unless you have at least 3 different use cases you're abstracting, and the test suite doesn't count.
vharuck 7y ago
It's surprising that wasn't being done in the first place. I used the Warcraft 3 map editor, and it was simple to include references to attribute values in an object's description. Don't know why the DotA2 team didn't port that feature over when moving to the new engine.

madeofpalk 7y ago

> Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date Not always - when you want to document the requirements (in whatever format), having them be separate from the code is often a plus. The code might implement the requirements incorrectly, so being able to recognise that is important. I find this very similar to writing tests that are separate from your implementation. In fact, Cucumber/BDD tests try to make product requirements executable to validate the software has been written correctly to meet the requirements.

somtum 7y ago

How does Millet and Tune's DDD book compare with Eric Evans? Are they both worth reading?

ptero 7y ago

> Documentation is essential. How things work is an important thing to document. I agree with this 100%. However, to be useful it needs to hit the right level of crudity. For most projects, a short (<10 pages) description of goals, design principles, architecture and an overview of interfaces is sufficient. It is best when this exists as a standalone document which is a required reading for any new developer. After this they can look at module descriptions, function docs, code, etc. and understand how to make sense of it and how to add their code without breaking general principles of the project. > Ideally it should be in version control and be generated from the code, because then it's less likely to go out of date. With this, I have some beef. In my experience the best documentation is the one that complements the code. Usually this means a short description by a human that explains what this chunk of code does and assumptions or limitations (e.g., "tested only for points A and B in troposphere") and IME most useful information is not derivable automatically. Auto-generated docs are very useful, but cannot replace clean explanations written by a human. My 2c.

roland35 7y ago
I think there is room for this to be two documents if a project is large enough - one which resides inside source control which explains the design and how it works, and one which is external (sometimes managed by corporate level document control) which explains the "so what", including top level requirements and so forth. These could be just one document if the project is small enough.
0xffff2 7y ago
I think there's a lot of ambiguity in the phrase "generated from the code". When I hear it, I think if docs generated from doc-comments embedded in the code, which hare clean explanations written by a human. They just have the advantage of being right next to the code, so they're a lot more likely to be updated when the code changes than an entirely external document. "Documentation" that is nothing more than the interface definitions in HTML for is worse than useless. I can get all of that from just reading the code.

collyw 7y ago

> Writing a few hundred pages of specification and handing it over to the dev team is waterfall, and it is _this_ that the Agile manifesto signatories were interested in making clear That doesn't sound too bad from a dev point of view, better than the opposite - half arsed specifications with no thought given to the important details. Though I can imagine a lot depends on what exactly you are trying to build.