1) Evaluation stage: Developer arrives at API docs with goal of determining whether framework solves problem within unique set of constraints. Expect him to skim docs, searching for keywords related to constraints, and/or any examples similar to problem.
2) Implementation stage: Developer has settled on your framework (at least initially), and is ready to build first project. Will either complete project, or abandon framework, depending on technical quality of your docs.
These two mindsets represent two components of a sales funnel. On the docs landing page, your primary goal should be converting developers from Mindset #1 --> Mindset #2. If you look at popular docsets, you'll notice that the intro pages tend to read like sales pages. Why should you use this framework? What are some popular production implementations? Any cool examples?
Deeper in the docs, you simply need solid technical documentation. Other comments here have great tips. Just keep in mind that Mindset #1 will barely skim these areas of your docs, but will definitely consider them briefly.
So, in brief:
1) Sell developers.
2) Write good technical docs.
Here is an example of 'sales copy docs':
!!! Gets your missiles launched in seconds!
!!! Produce reports of completed strikes!
!!! Makes a great pasta salad!
!!! Provides a C library and python, perl and ruby bindings for assembling, scheduling, executing, and reporting on minuteman launch capabilities for a variety of platforms.
!!! Supports only ARM and SPARC architectures.
!!! Requires 3 active nodes on 5 different networks for high availability.
!!! No REST API support.
Sales is not dishonesty, despite the stubborn misconception commonly held by engineers. In reality, sales is the process of convincing someone that Option X is in his best interest. There should be no trickery involved. If you're a good salesman, you can convince without dishonesty.
There are honest sales techniques, too. Dishonesty is a great way to burn your long-term social capital for short-term gains. Like, how I'd phrase that is your docs should either sell developers something they end up wanting, or help build a long term relationship by pointing out that it's not something they want.
Accomplishing these "salesy" tactics while not appearing needy or shoving bullshit down someone's throat is a very fine line. The world needs more technically informed writers, and more developers should work on their writing abilities. It's a definite art / science combination that makes most technologies successful.
On an API level, don't just explain what things do, but how to use it, what is the intention behind a particular call or method, and how it integrates with other pieces of the environment. If there are best practices, this is the place to call them out. And it does not need to be a tutorial, but if the class calls for a "usage sample", that is perfect for the documentation.
Pick on these:
1) What decisions did you take for the implementation?
2) What tradeovers are made (this is written like this because ...)
3) How is it supposed to be used
4) What is the common pattern for accessing the resource (instantiate it, factory, singleton, dependency injection?)
5) How does it relate with the rest of the codebase?
Now, this is PHP, but on other languages...
6) Is it Thread-Safe?
7) How cheap is it to instantiate a new object of that type?
I've also noticed a lot more packages (npm mostly) with synopsis sections which essentially forms a 'full example', I find these immensely helpful.
One of the best documentations ive seen in the last time was from phalconPHP http://docs.phalconphp.com/en/latest/index.html
Well written and many comprehensible examples within in the doc.
I think, that writing a good documentaton is harder than programming.
The relation to the rest of the codebase is something I don't really get: do you mean I should explain why this piece of code is consistent with other code? Or the documented code interacts with other pieces of code?
Then, partition your mind into two halves. The first half contains everything you know about the project, and the second half contains everything your imaginary new reader knows, which may be nothing.
Identify each difference between these two bodies of knowledge and, starting with the largest and simplest, write down what the reader needs to know in order to transition from one state of mind to the other, in as succinctly a way as possible.
If you start rambling, go back and edit.
I find this works for explaining many things, not just software projects.
Read other documentation. Discover what choices the writers made (implictly) and what works for you w.r.t. structure, clarity, completeness, conciseness. In your case, look for documentation of other (web) frameworks with a large audience, for example:
- Django: https://docs.djangoproject.com/en/1.7/
- Symfony: http://symfony.com/doc/current/book/index.html
- Rails: http://guides.rubyonrails.org/ and http://api.rubyonrails.org/
- What is this?
- What is it for?
- How do you use it?
- What's going on?
- Where do we go from here?
- What are we trying to accomplish?
- How do we accomplish it?
Also, include a good project summary. You'd be surprised how many projects don't include that. They just assume that everyone knows who they are and what their code does.
Also, please have an accurate changelog.
Presentation and audio recording:
Not kidding. Its an effective checklist and provides decent balance, at least a first guess at checklists and balance. Think of it like a development framework... for docs.
A really difficult startup problem (aka a good one) would be automation for doc writing. When you code its really easy to have automated syntax checkers and testing systems and A/B binary search algos to scan thru a git repo to find when a bug was introduced... and when writing docs its still the 1980s, maybe 1990s, you've got a spell checker and maybe a grammar checker and possibly some kind of "grade level analyzer" that just looks up and calculates average syllable length of words. There must be something better out there.
There have been no shortage of historical attempts at inline doc generators and template systems and markup language for technical docs. However, none have revolutionized the world, at least not yet.
(Edited to add, just caring about this issue puts you ahead of the pack, which is either a very optimistic comment WRT you, or very pessimistic comment WRT everything else on average... Glass half full or half empty LOL)
1) write a draft. make it correct, but don't worry about good too much yet.
2) teach somebody using the draft. Work with them and watch closely, make notes as you go.
3) revise draft.
4) repeat until good.
With some experience of this practice, you build up a decent model of the student/audience in your head and future first drafts tend to be better.
1) less is more. Writing less means fewer mistakes and faster reading. Think K&R, not Java for Dummies.
2) lots of examples. Every function description should include at least one realistic example of its use.
One may even consider tests as part of documentation because they are functional representations of the logic you've developed - they can be the examples that can show how to and how not to use the program.
Here is a link to the mentioned chapter and figure (15.3 A self-documenting program) from "The Mythical Man-Month":
- Please let me know if this link is failing, and I will try to find another source.
- It's no prose, so don't try to be arty.
- Keep it short!
- When in doubt, drop it.
- Use simple words. Not everyone is fluent in English.
- Any sentence with more then two lines is an anomaly.
- Be consistent. Avoid surprises.
- Usecases and Examples are important and may shorten explanations.
- Include common mistakes and their workarounds.
- You have to refactor often (>>20x).
- Use a versioning system like git or mercurial.
- Avoid abbreviations and introduce them at first occurence e.g:
concurrent versioning system (CVS)
- A colum shouldn't exceed 9-12 words (~60 chars) to improve readability.
- Keep your rules in a file (e.g: doc.playbook) and check them
- Let others proof read, or yet better find an editor.
- Try to be gender agnostic. Why? cautionary tale:
1st documentation inside the code should be used sparse. The code should be obvious, and PHP code could be readable, if you use good names, and proper indention. Comments should only point to traps and tricks.
2nd documentation for those who use your code. This should come in two flavors. You need manual pages for command line and styled HTML for browser. PHP offers XSLT making this task very easy. See http://kephra.de/src/php-xslt-doc/ as example. I'm sure that there are many more fancy PHP documentation packages around. But mine counts only 533 bytes.
3rd and last we have the documentation that describe the design of the project. I often use a MediaWiki + xfig for this, generating additional graphics with GNU plot or batik for SVG. But your mileage may vary here. PHP does not offer a straight solution to this wide problem, afaik.
It's therefore useful to tie your documentation to the code itself:
1. Generate documentation from the code where appropriate.
2. Automatically test examples in your documentation each time you regenerate it.
As for the documentation itself, I know of no good way to put yourself in the shoes of someone who does not know your API - you are just too familiar with it to be a good judge of the documentation. Instead, test it. Get others to read it and try to accomplish particular tasks, invite feedback (and be open to it - if they get something wrong it's not their fault, it's yours, they're the experts in how useful this documentation is so listen to them), and iterate.
1. Imagine you are a use who knows nothing about your framework. What would you need to know next?
2. Write that.
Step one is really really hard. It takes a powerful imagination to pretend that you don't know something and hop the fence from framework producer to framework consumer. There's no easy way to do this aside from practice and talking to users lots.
In terms of just generally writing better, here's some basics:
1. Revise. Revise. Revise. That writer you love's first draft is just as shitty is yours. The difference is you never see their first draft, you see their eighteenth.
2. Reading out loud helps a lot. Yes, even for technical docs. Yes, it feels weird. Do it anyway.
3. Brevity matters: you want to distill your knowledge to its essence. But note that it's a distillation process. In your first draft, just dump it all out. Worry about condensing when you revise.
4. The written word, especially technical writing, by default, comes across as emotionally cold and unfriendly. Words don't have facial expressions and tone of voice. While technical writing isn't read purely for pleasure, you'll get a lot of value out of trying to make it a little more engaging and pleasant to read. Don't be afraid of a little emotional language. You'd be surprised how much of a different starting a paragraph with "I'm really excited about this feature..." makes.
5. Give someone a couple of examples and they'll delight in finding the generalization on their own. Going the other direction is a lot less fun.
6. Different readers have different learning styles. You may have to say the same thing in a few different ways or a few different orders to reach them all. Balancing this with #3 is an art form.
The fact that you're asking at all is a great sign. (See! More positive language!) If you care about your docs as much as you do about your code, that is, by far, the most important ingredient to being a good writer.
For a getting started / user guide, give a higher level description of how components tie together and show end-to-end usage examples. The key here is to be succinct but include all the information that a new user will need to get started. Whenever someone asks a question, this is a good sign that information should be added to the docs.
Don't focus on the Perl language, just on their best practices for documentation. the guideline in terms of content are totally relevant for any language/developers and polished by practice.
Even if I chose to switch from Perl to python, I still miss Perl in terms of module distribution/testing/documentation.
Perl, and Perl community, I miss you, and I value what you learnt me :)
I advocate for people to be open minded and take good ideas without prejudice on their origins.
If you only read one link from that page, make it this one: http://jacobian.org/writing/great-documentation
Those two pages are well worth your time.
The most frustrating type of documentation for me is when there are usage examples but nothing else. Then, when I invariably want to use the library in a way that's slightly different than the provided example, there's no documentation available.
Start with a minimal set of standards and templates and build up, rather than over-engineering and not getting anything done.
One of the best examples I've come across is the documentation for Rackspace Cloud Files: http://docs.rackspace.com/files/api/v1/cf-devguide/cf-devgui...
But yeah, I'm a pretty heavy user of my own framework :)
In fact the best documentation I've seen (say flask, django) most of the documentation acts as support for reading the code.