2 ms·
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
by peterwwillis 12y ago
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.
- ThrustVectoring 12y ago>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.
- chatmasta 12y agoI 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.