Software Engineering Stack Exchange is a question and answer site for professionals, academics, and students working within the systems development life cycle. It only takes a minute to sign up.
Sign up to join this community
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?
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.
"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:
At that point, they're going to have more questions like
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.
