1. 27

  2. 5

    Something I’ve noticed is docs that are reference have a tendency over time to expand also into user guides.

    I’ve never seen it work out, as the two use cases are very different.

    One requires quite technical and specific information. If you mix in guides, the reader is left to carefully read the guide to see if there’s a subtlety explained therein that is relevant.

    The other is more along the lines of a tutorial. Mentioning all the fine print only confuses a new user, as such details aren’t relevant to them at this stage.

    1. 5

      Strong agree. Long ago, I gave a talk about this: https://air.mozilla.org/rust-meetup-december-2013/

      TL;DR, API docs, guides, and reference materials have three different audiences, and so need to be three different things.

      1. 1

        Sorry, I’m too lazy to watch the talk. I can understand the difference between API docs and guides. What makes reference materials different to API docs?

    2. 2

      To write good docs, you need to walk on a fine line between conciseness, completeness and clarity. Often, only one of these factors prevails, at the expense of the others.

      • Docs that are too long (or include too many details) = bad for conciseness and clarity.
      • Docs that are too short (or include not enough details) = bad for completeness and clarity.
      • Docs that are written poorly = bad for clarify.