Best way to create user documentation for open source software

Hi,

The time has come for QuPath’s user documentation to be completely rewritten… ideally in a way that makes it easier for others to contribute, and that can be more easily maintained across versions.

I was wondering if anyone has tips / suggestions / warnings for how best to do this?

The docs I wrote first are on a GitHub wiki, but I’ve been looking into readthedocs and am curious about anyone else’s experience of this.

I’m also very interested in any other thoughts to help with the decision-making, e.g. most appropriate CC license, where to host javadocs, anything else I might not have forgotten…

Thanks!

Pete

3 Likes

Hello Pete -

I don’t have any suggestions for frameworks or technical tools
for documentation.

I will say, though, that there is no substitute for being committed
to and disciplined about creating documentation, and keeping it
up to date.

Don’t rely largely (or solely) on automated documentation tools.
Tools (for example javadoc) can help with some of the donkey
work, but they don’t write useful documentation without guidance
(informative “doc strings” and cross-references, etc.). An
automated index of classes and method signatures is worth
having, but, absent an explanation of both the “what” and the
“why” of the classes and methods, and an overview of the overall
architecture and its philosophy, such an automated index is
less useful as documentation than the code from which it
was generated.

These automated tools also have the failing that they tell you
what there is, but not what there isn’t. Good documentation
will tell the user what reasonable expectations have been left
out and why – was it left out for good reason, or is it a feature
request begging to be made? – and suggest workarounds for
missing functionality, where possible.

Don’t let your documentation become too fragmented. It makes
it harder for the user to know where to look, and is more likely
to become inconsistent with itself (and the source code). I’m
tempted to say: javadoc, tutorials, wiki – pick two. (But that’s
probably excessively prescriptive.)

Be very, very skeptical of the notion that “We will write the code,
and the ‘community’ will write the documentation.”

In an open-source project, it should be easy for “others” to
contribute to the code base, but in a disciplined, organized way.
Documentation contributions should likewise follow a disciplined
protocol, and should have quality-control checks in place
equivalent to those used for the code.

I’ll also note that developers (in terms of knowledge, if not
temperament) are often the best positioned to write the
documentation for the functionality they implement.

Absent a structured documentation methodology, “community”
contributions to documentation are especially likely not to be
maintained across versions of the underlying code.

Just my thoughts …

I don’t have (and I don’t think there is) a magic bullet. Good
documentation is hard work. But software projects that invest
the additional resources to do the hard work required for good
documentation are more successful.

Thanks, mm

2 Likes

Thanks @mountain_man for your thoughtful answer :slight_smile:

I should maybe clarify that I think documentation is essential and absolutely agree that developers need to write it. I spend rather a lot of time on it myself, although it’s always a balancing act amidst other things. I’ve also regularly experienced that people using software that I have written have come up with much more creative and clever ways to use it than I ever would have (ahem…*)… so I think it’s also not good if it’s just developers like me writing it.

To date I mostly have experience of GitHub wiki and GitBook:

The trouble is I’m not terribly happy with either as maintainable in the longer term. I’ve also created youtube tutorials, which users seem to appreciate (inconveniently for me, since I don’t much enjoy making them…) although I think this isn’t sufficient on its own.

There are enough entirely new and/or revised features in QuPath that it seems the right time to consider dispensing with what the current documentation and starting again to create something better.

I feel the main thing I’m missing with the GitHub wiki is the ability to split it according to software version, which is something readthedocs offers. But I want to avoid jumping in and regretting it if there’s a better way…

@Research_Associate, @smcardle… oh, ok then, and @lmurphy

1 Like

@mountain_man & others, are there any projects you could link to that have particularly good documentation? I think it would be really helpful to have a gallery of examples to aspire to :slight_smile:

1 Like

Balanced by the number of active users, maintainers, financial contributions, etc…

I am finding readthedocs very uncomfortable and slow… but so far it seems to do everything that I would want. I do need to start almost everything from scratch though, except for the base text.

1 Like

As far as great documentation goes, for a users perspective I’ve always liked Django’s:

https://docs.djangoproject.com/en/2.2/

You can change the documentation you view based on language and software version.

They’ve also got a style guide and steps to write documentation like there’s which might be useful! https://docs.djangoproject.com/en/3.0/internals/contributing/writing-documentation/

1 Like

I’ve often wondered why documentation that obviously had taken a lot of effort to write often failed to meet my needs until I came across this article. The idea is that good documentation should consist of 4 types of documents to meet diverse user needs: tutorials, how-to guides, technical references and explanations. I don’t think the framework you use matters much as long as you have a format suitable for each of these types of document.

3 Likes