Hacker News new | past | comments | ask | show | jobs | submit login

You are not only writing documentation. You are also writing sales copy for your framework. Recognize that developers will come to your API docs with two possible mindsets:

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.

Disagree with the first point. Sales obscures facts in order to convince someone to use your thing at their expense. Docs should put facts out more plainly and turn away developers from your framework as quickly as possible. If it's not what they want, say so.

Here is an example of 'sales copy docs':

  Minuteman Framework
  !!! Gets your missiles launched in seconds!
  !!! Produce reports of completed strikes!
  !!! Makes a great pasta salad!
Versus an example of 'real docs' provides and requirements:

  Minuteman Framework

  !!! 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.

I see your point. However, sales does not necessarily imply meaningless marketing copy. You act as a salesmen every day, any time you try to convince anyone of anything. A good salesman is not dishonest. He's honest, understands his customer, and guides the customer to a (mutually beneficial) solution to a problem.

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.

>Sales obscures facts in order to convince someone to use your thing at their expense.

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.

One thing I would add onto the notion of documentation acting as a sales tool... even once you've managed to convince a developer to use your tool, he or she may need to convince their management of the same thing, so good documentation can provide them with the "sales" points they need to get your framework adopted by their company / team / project lead. Good documentation not only informs and excites the end user of the tool, but should also provide a basis of value for any other stakeholders in the outcome of its usage.

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.

There is also a difference between material intended to teach and material intended to serve as reference.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact