1

I often need to include summaries of source code or tools, for example on GitHub. It's useful to have a section that describes how to use the component. The "Use" vs "Usage" debate has been answered in another thread, and the consensus seems to be "Use use", however that seems awkward as a section title. For example:

Gizmo

The Gizmo recombobulates the froop flux capacitors.

Use

  1. Download Gizmo
  2. Find your flux capacitors
  3. gizmo [-fp FroopLevel] FluxCapacitors

Contribute

Send pull requests to this.guy@emails.com

"Instructions" isn't clear because there are at least 2 different audiences to this text: developers interested in contributing, or users interested in using the tool. Instructions could refer to multiple use cases, so it's ambiguous. The same goes with "How To".

What is the appropriate word for the second section title in the example?

Thanks for your time.

Improve this question
4
  • Do you have an actual question in here somewhere? (Even if you do, though, this looks likely to be closed as "opinion-based" writing style advice.) – Hellion Sep 8 '14 at 15:52
  • Explicitely asked the question in the edit. – Guillaume CR Sep 8 '14 at 17:37
  • Documentation in Perl's CPAN modules use the word "Synopsis". – Dan Bron Sep 8 '14 at 18:04
  • 1
    This is the synopsis of a man page, not a project repository. The audience of that web page is strictly people who will use that component, not people who want to contribute to it or end users. In that case, synopsis, or summary, unambiguously refers to the use of the tool. – Guillaume CR Sep 8 '14 at 18:27
0

The appropriate word in this context is Usage.

Improve this answer
3
  • Not sure; I did my PhD in CS and have downloaded hundreds of software packages in that time, and usage is always the word used in these readmes. It's the "industry standard term" for these readmes, in my experience, so I think the OP should follow suit. – Tommy Sep 9 '14 at 12:15
  • Fair enough. I have grand designs to push CS terminology in the right directions by using this site, but clearly there is no better and immediately available term for this case. – Guillaume CR Sep 9 '14 at 14:04
  • @GuillaumeCR well I think you have a great point, but it intends on what you are trying to do. If you just want to write these user guides, I would stick to the industry standard since more down loaders/users will be familiar with it. But if you are trying to revolutionize the way they are written, and are willing to accept non-familiarity in doing so, then I think I may not have given the best answer because I don't actually know if its grammatically correct. I just know people use it for this =). – Tommy Sep 9 '14 at 21:19

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.