3

My application is meant to be used by regular everyday users, but may also me modified freely by developers. These two audiences (users and developers) require different information.

Should my README be targeted towards users or is it more proper to target the README towards developers?

  • 3
    Why are they the same file? – user40980 Apr 30 '15 at 21:45
  • 3
    There's no industry standard here, other than README means "Read Me." Do what makes sense. – Robert Harvey Apr 30 '15 at 21:49
  • 2
    Just as one example, I believe the Github convention is to have a "Readme.md" and a "Contributing.md". Pretty self-explanatory. – Ixrec Apr 30 '15 at 21:53
  • 1
    What is the Readme distributed with? The application or the source? In a sense, that is the target audience. – Kristian H Jul 14 '15 at 15:46
  • 4
    If you expect "regular everyday users" to open a readme file before using your product, I expect you're in for a rude awakening. :-) – Eric King Jul 14 '15 at 15:48
5

A "readme" file is simply "what to read first." Who you are means nothing: open the readme first.

From there you should direct users to the proper documentation:

  • Have links to more appropriate documentation. README simply is a starting point. Explain where to find the installation documentation. Explain where to find developer documentation. Usage documentation. Changelogs. README should be a signpost: the one place you can look to be directed to where you really need to go.

  • Many pieces of software have HTML READMEs with navigation and such, often included with the software or source code. This is good because formatting and hyperlinks are more useful than plain text. Your simple README text file might direct someone toward a more expressive document.

  • Perhaps have links to GitHub or wherever the software lives, which generally also has more documentation as well. GitHub documentation is more closely tied to the structure of the code, since its markdown files live in source folders. This would be a great place to put developer documentation.

  • Whatever the documentation, have links to documents for "I just want to install, what do I do?" and "how to compile from scratch on supported platforms."

  • Finally, developer documentation is well-placed in Doxygen, JavaDoc, or GitHub documentats. These are standard documentation formats that developers are expected to know how to build and read. Being more technical users, developers require less hand-holding. Provide a makefile, Ant script, or Visual Studio solution, and they should be able to figure it out.

As Robert Harvey alluded to in his comment, there is no standard thing to do. Do what makes sense for your software and its intended audience, but provide useful information regardless. As long as you leave some breadcrumbs in your README, you should be fine: its purpose is to be a signpost.

| improve this answer | |
3

"Developer" inherits from "user". If it's good for users, it will probably be good for developers. True, users don't often read documentation. But if you have 100 users to each developer and even 1% of users read READMEs and, say, 50% of developers read them, you'll still have twice as many users looking at the README than developers. So cater for both.

Both non-developer users and developers will want to know two things to begin with:

  • What does it do?
  • How do I get started?

At that point, they're going to have more questions like

  • How do I make it do the thing I want it to do?
  • What does this thing do?

But the answers they are expecting may be very different (they may be hoping for answers to questions like "which button do I press?" vs "which source file do I need to edit?"). That's when you break it out into different documents. Point to the tutorials for everyone first, and then link to the developer documentation.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.