Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

We are looking at revamping documentation across our product line. Part of that includes reference manuals for a programming language used as part of the system.

When writing a reference manual for a programming language, what is the best way to structure it for maximum usability to those new to the language?

What are the key aspects for each keyword documented?

  • Syntax
  • Description
  • Arguments - if applicable
  • Return values - if applicable
  • Example of usage?
  • Any others I'm missing?

Should concepts (such as locking strategies, performance related details) be also documented in this reference manual, or is that a separate document?


This is for external consumption. We already have full doc sets (see: http://www.rocketsoftware.com/u2/resources/technical-resources). Working out what we should do different - I already have my ideas, but as always, I try not to rely solely my my opinion.

Audience: Technical developers using our database(s) & tools to produce software across many industries.

share|improve this question
    
Why would you need to document the language? Is it an esoteric or custom made language? Doesn't it have documentation already? And if not, why did you choose it in the first place? –  Yannis Rizos May 14 '12 at 4:02
    
@YannisRizos - I think you can assume it's a custom scripting/macro language, not that they intend documenting C++. Generally the docs for such a language is the parser source - since the implementer of the language is often the main user –  Martin Beckett May 14 '12 at 4:28
2  
@DanMcGrath Well, yes, knowing the audience and level / volume of existing documentation would affect how I would write a reference manual. Will it be only for internal use? –  Yannis Rizos May 14 '12 at 5:51
1  
@Telastyn - Yes, it is public. We have much more than just reference manuals, but this question was specifically on that aspect: rocketsoftware.com/u2/resources/technical-resources –  Dan McGrath May 14 '12 at 13:47
1  
Take a look at Lua's docs for a great example of a well-written and focused reference manual. Introducing the language is the job of a separate book, Programming in Lua. The division of responsibility works well, at least for me. –  yamad May 14 '12 at 18:35

2 Answers 2

up vote 10 down vote accepted

Organize documentation in accordance with target audience needs.

In your case, primary audience are apparently software developers. The parts to consider here are to address different "sub-audiences" of this one:

  1. Hello World.
    Those willing to quickly get the taste of it, just build and run sample application to see how it looks like.
    Think of the audience like one addressed by MySQL "15 minutes rule":

    ...a user to be able to have MySQL up and running 15 minutes after he finished downloading it.

  2. Fundamentals.
    For the guys willing to quickly learn things necessary to start producing working software.
  3. Advanced topics.
    For developers already well familiar and practiced with fundamentals, interested to know what is there beyond. Mainstream topics that have not been covered in Fundamentals.
  4. Style Guide / Recommended Practices.
    Subjective advice and guidance for those interested in the way how you recommend to do things.
    The question does not indicate whether this could have a substantial audience in your case, so the options to consider are to include it as a part / appendix of Advanced topics or even drop it completely.
  5. Quirks.
    Obscure topics, outside of mainstream, that might be of interest to pretty limited fraction of your audience. For example, if you have legacy line, or stuff like upgrade / migration / interoperability with legacy - put it here. If there are some side effects for some function at particular "exotic" environment, it goes in this part.
Your secondary audience are maintainers of the manual. These guys can make or break how things work for your primary audience, so you better take care of their needs and issues.

What if something in the manual is questionable / ambiguous? What if it turns out that thorough explanation of particular concepts would make that manual too hard to read? What if it turns out that particular version of the manual has mistakes?

Two things to consider for maintainers are:

  1. Technical/formal specification.
    Whenever there is a questionable / ambiguous / hard to explain topic in the manual, the reader can be referred to particular paragraph in the specification for a strict and clear, "official" statement on that. Strict and complete (and most likely boring) description of language syntax would better go there.
    Paramount considerations for Specification are technical accuracy and completeness, even if these come at the expense of readability.
  2. Online supplement.
    Just reserve some URL and put it in the beginning of every document you release, so that the guys wondering what the hell they have just read could go there (instead of pestering manual maintainers) and find the mistake explained.

    Errata > Fundamentals > Release 2.2 > Typo at page 28, second sentence starts with luck, read lock instead.

Concepts such as locking strategies, performance related details should be included (possible partially) in where you expect target audience need it.

E.g. manual maintainers would apparently be interested in a complete, accurate description of concurrency and locking in the formal specification - put it there. Readers of Fundamentals or Advanced topics might be interested in an overview / introduction / guide extracted from specification and tailored to their needs etc.


It could be helpful to arrange a comparative study of reference documentation provided for other languages like yours. Aim this study at leveraging experience gained by those who did it before and learning how to avoid mistakes they made.

The last but not the least, consider setting up documentation development in a way similar to software development. I mean things like version control, regular releases, issue tracking, quality assurance etc. You may want to make some compromises though if it turns out that your technical writer(s) are not really comfortable with stuff like that. We don't want to get crappy content "in exchange" for perfect development process, do we?

share|improve this answer
    
Excellent answer. Thanks gnat –  Dan McGrath May 14 '12 at 13:24
    
@DanMcGrath one more tip for doc development process: consider push-track-backout-repeat approach. 1) push tech writers to stricter process 2) track doc quality while pushing 3) if there's quality decline, backout to "softer" process 4) some time later - after they got used to current level - repeat push to stricter one. And so on, and so on until you're 100% there. :) –  gnat May 16 '12 at 10:46
1  
I have one quibble. What you've described is a tutorial or a set of tutorials. A tutorial is not a reference guide. A tutorial describes how the language works, while a reference guide catalogs the elements of the language. Both a tutorial and a reference guide are important, but they're complementary. –  Gilbert Le Blanc May 16 '12 at 13:31
    
@GilbertLeBlanc question was about "reference manual" which I (and I think Wikipedia) consider wide enough to cover stuff in my answer –  gnat May 16 '12 at 14:02

The first thing that you need to do is to evaluate the audience. Is your audience Linux kernel hackers or are they hardware designers who use software tools to do a job but aren't interested in software per se and don't have a CS background. Electrical engineers are likely to not be completely clear on the differences between const and non-const arguments, pointers to objects versus references, etc. If your primitives have overloaded names, then you had better explain that concept at an appropriate level for your audience, which might be nothing if they are C++ programmers.

The second thing that you need to evaluate is the granularity of the primitives of the language. The finer the granularity, the more you will need to provide examples of use in proximity to the syntax specifications of each primitive. That is, if you have a low-level primitive that instantiates some context, and you need to operate on it with three other low-level primitives before you can do anything useful, then you better have a complete example of some useful function close-by in the manual. See the online openssl documentation for an excellent counter-example of nearly unusable documentation.

Be sure to include explanation of any side effects of your functions.

In any event, if you don't want your customer's programmers to curse you every night before bed, include plenty of tested example code that performs some high level functional primitives. Make sure that the examples are not just snippets of code, but complete and compilable or runnable out-of-the-box.

Traditionally, tech writers have distinguished between reference manuals and user guides. The reference manual usually includes the syntax specifications, an intelligible definition of the functions or primitives, discussion of gotcha's, performance and side effects, and a short example usage. The user guide includes more extended usage examples and discussion of wider engineering issues. The Kernigan and Ritchie "C Programming Language" is an excellent counter-example to this convention, but this approach works only when the language you are documenting is relatively simple.

The author was manager of the Engineering Services Division at Ready Systems Inc's development center between 1987 and 1991 with responsibility for managing a team of five tech writers.

share|improve this answer
    
Thanks for the answer @Eli –  Dan McGrath May 14 '12 at 13:48

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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