There are no documentation standards for Ruby/Rails really (I'm working on an entry on this...so bare with me), and so I'm sort of left to my own devices when analyzing quality. The plan is to allow users to write their own analyzers and thus let them create their own quality standards, but it would be nice to include a "default" quality analyzer. The problem though is not what it should do, but how?
Quality is so subjective, that if we're to do a midline, objective analysis, a standard needs to be developed or some sort of criteria needs to be met. This entry is little more than a plea to you guys and gals: help me create one! What do you think makes good quality API documentation? I'll reconcile your responses into something workable in a future entry and that will become dcov's standard criteria set (until we decide to change it ;)). Here are a few of my ideas:
- Parameters should at least be mentioned.
- Options hash must be documented if present.
- Default values must be explained.
- A return value description should also be present, if there is a return value and it is not apparent.
- Examples! Examples! Examples!
Let me know what you'd like to see.
16 comments:
I think there are 2 kinds of consumers for documentation: future maintainers, and library users. Future maintainers benefit greatly from code that reads like pseudocode; library users don't see the source and need lots of extra words basically explaining that the unseen source does.
So, keep in mind that code can be its own documentation for some folks, not for others. Comments not extracted by rdoc only benefit some folks.
The BDD folks will also point out that tests (a whole nuther file to parse and consider when talking about the docuemented-ness of a source file) are documentation of what the code they're calling is supposed to do. Again this is less useful if you can't read the BDDified test source code, or a documentation format generated from that code.
I've been working on a way to do doctests in ruby, the code itself isn't documented (my apologies) since i only did it as a kind of proof-of-concept, but it has quite some appeal to me as a way to ensure docs really match reality when it comes to examples.
See the source here: testdoc source
The specs explain how to use it.
I have a newer version on my notebook that supports setting up contexts (kind of 'before :all do') before running the testdocs. Will push that a bit later.
Don't forget a simple README and introduction that explains how to start using the project.
I'm continuously appalled at most documentation being a link to some blog post somewhere else rather than having a decent README that explains what the library is and a nice trivial example to help get you started playing with the codebase.
We've made an effort in the last year to try and document the bioruby package as good as possible. With a standardized way of documenting. The README.DEV in the package explains what format to use to document classes, methods, return values, ... See here.
I think that eventually, the tool will need to maintain a documentation quality metric. This can probably be tied to the number of times the documentation is updates / number of times the source is updated. Code commit analysis can probably yield the raw changes.
The real problem (IMHO) with documentation quality is that it's at it's highest after the code is written initially. The documentation frequently gets ignored as the code is maintained.
A bibliography is a list of works by other authors that is relevant to a book opr article and is usually listed at the bottom or at the end of the work. Bibliographies are extremely useful but little known SEO tools. apa editing services
From a freelance or independent consultant's standpoint, marketing writing skills to potential service buyers is important to keeping any consulting business thriving. homepage
click here. You will enjoy a close relationship together with ease of getting exactly what you wanted.
Education involves the development of an individual’s intellectual, emotional, social and physical self through the learning process. In short, it grooms, builds and develops and individual’s personality on the whole.visit website
"Thoughts on Documentation: Quality" is very useful article for those people who reads week. I am practically satisfied with your great work.You put truly extremely supportive data. This http://www.phdproofreadinghelp.com/our-academic-proofreading-services/ will help you to know more.
Thanks for sharing.
Good information.
Thanks Art, this is a the complete much important and useful posting for job seekers. Its really an outstanding analysis. Job seekers should visit in addition to the site of top recruitment consultant of Illinois. Thanks considering more.check it for dissertation editing help.
Good information.
Book editing providers understand just how to proof read and organize your own records so that it matches you and your writer's special requirements. Packages for editing novels do not comprise changing word choices and tagging paragraphs. visit website and it'll help you to know more about the academic papers writing.
Post a Comment