Update documentation chapter

[c-martinez]

Update documentation chapter

[LourensVeen]

Just browsing through this chapter makes me feel a little overwhelmed. I'm supposed to do all that and also write the software itself? It feels like someone Googled everything documentation-related that anyone has ever done and copy-pasted it in there.

I think first of all that this page should be organised by audience, and possible split into two. There are two audiences, users and developers, and a stakeholder, the eScience Center. And there are two topics: the software, and the project. Here are the headers from the current text, arranged like that:

Users

Software

• README (if used as homepage)
• Well-defined functionality
• API documentation
• Usage documentation

Project

• How to file a bug report

Developers

Software

• README (if used as developer landing)
• Source code comments
• Development setup

Project

• Contribution guidelines
• Documented code style
• Explained meaning of issue labels
• Code of Conduct

eScience Center

• DOI or PID
• Software Citation

I think it's telling that we need to explain the meaning of issue labels and get a DOI, but that there's no mention of having a really good tutorial to lower the threshold to entry for the users, or a short overview of the organisation of the code to help new developers.

So let's think about who the audience is, what they want, and what they need to achieve that:

• Users
  • Learn what the software does and whether it is suitable for their problem
  • Get started with the software
  • Learn how to do something specific
  • Look up details of the user interface
  • Getting help
• Developers
  • Learn how to interact with the project
  • Learn how the code is organised
  • Understand the details

I'm going to omit the eScience Center as a stakeholder here, that's not documentation but advertising. Nothing wrong with it, but I think it should be a separate section.

Users

Learn what the software does

This needs a homepage, either the README or a separate webpage. It should briefly describe what kind of problems the software can help the user solve. Don't forget to add a brief statement about the legal status of the software (e.g. "It's licensed under the Apache 2.0 license, and all dependencies use permissive Open Source licenses.)

(Advertising has a big share here, and the advertising page should say that text should be in the GitHub Release description because that gets picked up by Zenodo and presented as the main description on the Zenodo page for the software. It should be put in the RSD as well.)

Get started with the software

A nice tutorial. Make sure it's written from the perspective of a user who doesn't know anything about the software. It's really easy to forget to mention some of the context that the user doesn't have, and make something that's difficult to understand unless you already know what you're trying to learn. Let someone unfamiliar with the software proofread.

Learn how to do something specific

YAtiML has a Recipes section for this. Recipes (or examples) are mini-tutorials with copy-pasteable code for doing something specific and a bit more advanced than the basics in the tutorial. They should explain how the code works, so that users can adapt it to their actual problem.

Look up details of the user interface

API documentation for things with an API (use inline documentation and a tool like Sphinx or Doxygen to generate this), or if it's got a GUI, tooltips for GUI elements and possibly help pages.

Getting help

File an issue, ask on Gitter, or whatever venues have been set up for this.

Developers

Learn how to interact with the project

This is the Code of Conduct, Contribution Guidelines, code style, and sure, even issue labels if you feel the need.

Some Codes of Conduct can sound very legalistic, which I find paradoxical because the key take-home message of a Code of Conduct should be that we're all humans with feelings that can get hurt. Instead the reader gets treated like a robot to be programmed with correct behaviour.

Last time I used the Python template, it produced a huge wall of text for Contribution Guidelines that set up a complex bureaucracy. We're not trying to run Python or Debian here, our projects are small. So I tend to rewrite that into something that people may actually read and follow. Key points: discuss before you start coding new features, make a pull request when you're done.

Learn how the code is organised

This is the "Getting Started" for developers. When you're new to a code base just figuring out where to start reading is already hard enough. So having a brief overview is good. Some things to consider describing:

• here's how the directory structure is organised
• here is a diagram of some critical classes and how they're connected
• key functionality X is implemented in function Y in file Z
• the main entry point is here

Understand the details

Write docstrings (comments) for functions. Describe what the function is trying to achieve, not what it does (the latter should be obvious from reading the code itself). These shouldn't end up in the API documentation, because that's confusing. Programmers will be reading the code together with the docstrings.

I agree with Jason on documentation-driven development: the general idea is good (Rule number 1: Engineering begins and ends with People) but doing it strictly doesn't make sense because you can't design the perfect API or UI in advance, you're going to make some improvements while implementing and that's a good thing. Same with test-driven development by the way, but that's a different topic.

[LourensVeen]

I use ReStructuredText you insensitive clod!

[c-martinez]

@jmaassen, @fdiblen, @egpbos, @LourensVeen -- I'm sure you might have some good pointers?

[egpbos]

I do have some ideas for improving this chapter.

1. The chapter imho is way too heavy on details and "must haves". It neglects the most important part: to actually encourage and help engineers to document things at all.
   1. Documenting code is sometimes as important as writing the code itself. Not writing documentation, tailored to your users' needs (know them and you know all your "must haves"), simply means nobody will use your code. If that is your goal, then fine, don't write docs. If it is, then write them and do it from the start, because the task will only become more daunting the longer you postpone it. DO IT NOW! Yes, you too, dear reader (and yes, you too dear writer of this comment :P)! Maybe we should even advise "documentation driven development": start with documentation, e.g. with your ideal user example, and then write the code that makes it so.
   2. You help devs not by writing a long list of things they must do in a randomized order, but by making templates for them that have all the sections they will typically need and that they can easily remove if they don't need it. We can easily make templates for README.md, CONTRIBUTE.md (which imho should include basic developer documentation), a code of conduct and a user manual.
2. The English can be improved.

So, basically, what I'd suggest we do is remove most of the chapter, replace it with a cheerleading section like the point above ("DO IT DO IT DO IT NOOOOOW") and write some template files that people can actually use immediately. We can start for instance from the Python template documents and remove Python-specific things.

[c-martinez]

Great! I'm not 100% sure that having a template is the most helpful for writing docs. My guess it that just having some guidance (description of what makes good docs and couple examples) might be enough. But open for discussion.

Can I suggest 2 practical actions:

• If necessary, bring it ups as a discussion topic at the SIG
• Block some time to work on it (e.g. during the next guide sprint 16-20 May ;-))

[jmaassen]

Well... what should be in your documentation very much depends on what kind of software you are writing, and who the documentation is meant for. 4 types that immediately come to mind are:

• user documentation for an application (if you click here, this will happen, use these command line parameters, etc.).
• user documentation for a library (function X expect these parameters, performs task Y and returns Z)
• documentation on how to build, install, etc.
• developer docs (this is the architecture of the software, this is how you extend it, etc.)

Each of these tends to have their own logical location and technical implementation; interactive help for a graphical application, something like javadoc for function descriptions, and markdown in github for building and developer docs.

In my opinion, documentation driven development only makes sense if you are 99% sure beforehand what you are going to build. In research project this hardly ever happens, and even in business applications this tends to be an issue... This doesn't mean you should ignore documentation until the end. Documenting the functions you implement on the fly is good practice and adds only little overhead. Just be prepared to keep their descriptions up to date once you change the function (again and again) ;-)

[bouweandela]

Related to the-turing-way/the-turing-way#879 and the-turing-way/the-turing-way#2020

[egpbos]

I was just brainstorming on options, so sure, I agree that documentation-driven development won't work everywhere. What I was trying to argue is that the biggest problem with writing documentation is actually motivating yourself to do it, which is proven by the loads of undocumented code that exist in the world.

The actual guidelines can be just a very short bulletlist (that will then automatically be easy to maintain so we won't have this discussion again in 5 years), something like the summary @LourensVeen wrote (ok, I guess adding the short explanations is nice as well, as long as I get a nice copy-pastable list/table of contents on top 😄).

But we should spend time on motivating people and lowering (psychological) barriers.

Anyway, that's my two cents.

I agree that it would be better to have the chapter (in whatever form, I hope short and motivating :P) in The Turing Way, since it is so generic. And also agree that it would be nice to write it during a next sprint.

[LourensVeen]

Well, motivation should be easy. At the eScience Center we always write software for others, and those others won't be able to use the software without documentation. So either you write documentation, or you'll have wasted all your effort.

[fdiblen]

My 0.2 cents:
There should be two types of documentation.

• User documentation
  • Explain what problem the software solves and what it does not
  • List of requirements to use the software (both data and software)
  • Instructions to use the software
  • If possible, add screenshots, a link to a demo or a tutorial -- yes that should be in the documentation :)
  • Alternative options to show how your software is different
• Developer documentation
  • Software architecture
  • API documentation (if has one)
  • Dev dependencies
  • How to set up a development environment
  • How to contribute

Both types of documentation should grow with the application. The documentation should have priority over adding new features if the changes are affecting

1. the users, e.g. users need to install new dependencies or there are UI changes
2. the developers, e.g. there are new components or services added, or the behavior is different

Note: let's not generalize documentation by having a template. All software should be treated separately.

[egpbos]

What is the difference between a list of bulletpoint things that you have to add manually and a template where those bulletpoints have already been converted into headers in Markdown format? Seems to me like the only difference is that the latter is copy-pastable and hence more convenient and practical. You can even add (commented out with <!-- ... -->) the motivations/explanations for each header. I guess I'm missing something?

[bouweandela]

pandoc README.md -o README.rst would fix that

[bouweandela]

A documentation chapter is more appropriately located in The Turing Way.