The order Josh mentions seems correct, but usability and ease of consumption is
just as important if not more as correctness and coverage.
In technical writing, the key elements to usability and ease of consumption are
findability and searchability. Findability means finding information for
something you want to do without knowing what it is beforehand. Searchability
is finding information you know about using
the terms that you know. The key to effective documentation is that
information is both findable and searchable in "terms that the users know". A
simple example is gossip. If you know nothing about Cassandra, you probably
understand that nodes talk to each other, which you might search for using
"internode communication" or "network communication".
Without the ability to locate information you want, correctness and coverage
are meaningless.
Another principle that makes good documentation is that they are
solution-based. Two examples are replacing a node and adding a node.
Another important feature of being able to produce accurate and complete docs
is the ability to reuse information. Using the previous examples, replacing a
node and adding a node, may have some of the same steps. Reusing information is
not saving time by writing only once, it's about making sure that when
information is updated, it's updated everywhere it needs to be (especially in
places you don't know about). Having a single source for reusing information is
essential to making this happen.
Also, related to reusing information, the ability to pull from a central
location using includes/shortcodes/etc. can ease the testability and
findability of code examples used in documentation. Rather than scattering code
throughout the docs, you can store the code snippets in their own repo. For
instance, asciidoc has such a capability (amongst others):
[source,ruby]
include::example.rb[]
The last feature I want to mention that contributes to good documentation is
semantic structure. The idea of semantic structure is similar to
object-oriented programming, where objects contain data. So instead of manually
defining all the attributes of the warning, you can just declare the warning
and add the data. For example, suppose you want a warning that says "Don't do
this, it will kill your system!" In a non-semantics authoring, such as Markdown
(designed as format for writing for the web), you'd have to define each element:
**Warning**
Don't do this, it will kill your system!
The problem here is not so much having to define each element but that a
different writer can do something different, such as vary the marking from **
to *, as there is no enforced structure:
*Warning*
Don't do this, it will kill your system!
Although this is a very simple example, not being able to enforce a standard
can be confusing to the user because clues to using the documentation lack
consistency and refinement.
In semantics-based documentation, such in reStructuredText, you can just write
. warning:: Don't do this, it will kill your system!
and every instance will be consistent.
I realize that everyone wants something simple that they don't have to learn,
but doing so will:
1) Decrease the efficiency of writing docs, which reduces the likelihood of
complete coverage.
2) Reduce correctness, because the writer does not necessarily know everywhere
information needs to be updated.
3) Diminish the usability and ease of consumption. For example, a lack of
consistency reduces the ability of the user to quickly scan a document for the
information they need and appears amateurish.
On 2020/05/04 15:13:49, Joshua McKenzie wrote:
> I've been mulling over this topic the past few days as we often seem to get
> mired in debates over technical details of offerings without a clear value
> system to weigh them against one another. In the case of documentation, I'd
> propose that we think about this from the perspective of the users of the
> documentation. I suspect (and would love to hear points of view for or
> against this claim as I do not have first-hand knowledge) that doc users
> would care about the following in this order:
>
> 1) Correctness
> 2) Coverage
> 3) Usability and ease of consumption
>
> Assuming we can get a simple list of traits to optimize for, it may be
> helpful to weigh the pros and cons of various documentation frameworks
> against how they facilitate or deliver against those metrics. For example:
> ease of developer ramp and contribution to docs would increase Coverage,
> where more robust tooling and inter-linkage could contribute to ease of
> consumption.
>
>
>
> On Fri, May 1, 2020 at 1:52 PM Jon Haddad wrote:
>
> > We've already got Sphinx set up, so you can contribute today. There's a
> > docker container in the `docs` directory and a readme that can help you get
> > started.
> >
> > On Fri, May 1, 2020 at 10:46 AM Chen-Becker, Derek
> > wrote:
> >
> > > From the peanut galler
