I hope I put this question in the right place.

Currently, I am working on a huge software project. Within this project, we use a lot of different terms, words and verbs. We want to write down all terms with an explanation of what we actually mean with it. Also, we want to write down when to use which word.

For example, we have the term "challenge" with it's explanation. Whenever you are going to create a new challenge, the button should say "Create challenge". When you are in the form, the button to actually save it should be named "publish".

I am wondering if anyone has some sort of guidelines or an example of how to write the terms with it's explanation down and all rules related to the use of words.

I could of course create a glossary, but where to put all the rules then? Should it be 2 separate documents? Should I put the rules next to each word?

Looking forward to what you all are thinking. Thanks in advance!

closed as off-topic by Colin Fine, Ronan, Rory Alsop, Kristina Lopez, user66974 Sep 4 '14 at 20:04

  • This question does not appear to be about English language and usage within the scope defined in the help center.
If this question can be reworded to fit the rules in the help center, please edit the question.

  • 5
    This question appears to be off-topic because it is about the use of English words in a user interface. This is a very specialised field, with only marginal connection to English language and usage. – Colin Fine Sep 3 '14 at 15:01
  • You're almost certainly going to have to do it yourself. A spreadsheet won't work, believe me. Better a list of the metaphors in use in each division, with examples. Presumably all of these terms represent variables, routines, daemons, apps, or other named entities in the software project. There should be a list of such names in the software, perhaps one list per project division, and that can serve as a basis for the terms that don't appear as named entities (and why don't they, by the way?). – John Lawler Sep 3 '14 at 15:01
  • Regarding off-topic. I wasn't sure if the question was in the right area. However, I don't think it would fit in an general programmers place neither, because I suspect multiple people working with languages etc can have this problem. It's not a software problem, it's a language problem, since you could easily convert this idea to writing a book instead of a software program. So to me, this seems to be the best match. However, I am open for suggestions which place would be better. – P.T. Sep 5 '14 at 8:50
  • 1
    @JohnLawler Thanks for your feedback! – P.T. Sep 5 '14 at 8:50
up vote 1 down vote accepted

I had a similar problem when writing a list of places/names for one of my books. This is my solution of using columns but I am not sure if it quite answers your question...

Term (tab between these headings) Meaning (one one line and then explanation underneath)

Challenge (explanation) (when/where to use)

Line up the explanation underneath the Meaning heading (or use the Columns tab in Word to automatically sort this for you)

Hope this helps and makes sense

  • Not entirely sure if it will fit, but I think it might come close. Will give it a try :) – P.T. Sep 5 '14 at 8:46
  • ok, let me know how you got on :) just curious though I am not sure in what format (word, excel?) that you are writing your list – Madeleine Thomas Sep 5 '14 at 15:04
  • Thanks. :) currently I divided everything over multiple line. I am starting with the term. Underneath a short description followed by how to use. On the next lines, I add additional data. For example "actions" which describes if you "create" or "add" a challenge. Same for edit vs update vs change and delete vs remove. In the following paragraph I write down any additional rules like the "states" a challenge can be in and of which "fields" it consist. I hope you understand it a bit. (Hard to explain in a comment ;)) – P.T. Sep 9 '14 at 8:42
  • I use a lot of tabs in mine, but as long as it looks as you want it and makes sense that's good :) glad I could help – Madeleine Thomas Sep 9 '14 at 9:09

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