Start to write a `Definition of Done`. Then make it a guideline for releases

[KurtPfeifle]

Start to write a "Definition of Done". Then make it a guideline for releases.

---

_{(Use comments below to collect ideas and bullet points.)}

[KurtPfeifle]

• For all tools which AppImageKit users or packagers can use: provide authoritative "manual pages".
• Provide these manual pages in various formats so they can be used however the consumer is most comfortable with: Markdown, man (groff), html, epub, plain, ...
• Prepare this documentation package in a way that it is easy to be included by distro packagers in their respective distros.
• Do not exclude to document stuff that is not directly a command line tool! Also topics which commonly would go into Section 5 ("File formats and conventions") and Section 7 ("Miscellaneous") of the classical Unix manual page collection need their authoritative documentation.
• Whenever a change adds a new functionality to a tool, the release does not take place unless it is also documented in the respective manual page.
• For any new tool a new manual page needs to be written.

[TheAssassin]

@KurtPfeifle good idea. @probonopd planned to maybe switch to another documentation system.

Although @probonopd favors a Markdown based solution, I think it might be worth changing to Sphinx, which e.g., powers https://readthedocs.org/.

We can store the files in a Git repository (which I will mirror to my private Gitea instance) or, even better, right inside the AppImageKit repo in a doc/ directory, and then deploy it on my server on the subdomain https://docs.appimage.org/.

Sphinx has tons of features, including a man page generator (i.e., write the page in Restructured Text (ReST, the format which Sphinx uses), then generate a man page, an online HTML version, ...).

People which don't know ReST can always write Markdown, which can be auto converted to relatively good quality ReST. And ReST isn't that complicated so that people can always make changes without learning all of ReST. PRs without proper formatting can be edited before merging, but that'd be required for badly formatted Markdown as well.

[KurtPfeifle]

I also prefer to write input as Markdown.

I know ReST/Sphinx may be more powerful, but I doubt we need all that power. Thing is, basic Markdown works with knowing only about a dozen different "markdowns" already pretty well. And I meanwhile know almost all the tricks, especially when it comes to post-processing it with Pandoc (which can output man pages, as well as HTML, EPUB, JSON, LaTeX, ConTeXT, PDF, DOCX, ODT, ICML, RTF, ASCIIdoc, DocBook, MediaWiki, ZimWiki and some more).

ReST/Sphinx is a whole different beast for me. I'm currently not willing to put in the effort to learn all the fine details of ReST (when I know my way around Markdown already) and Sphinx (when I know Pandoc already) and then also move to a Python platform (where I'm blindfolded so far).

ReST/Sphinx to me looks like a whole framework to b handled.

Pandoc is a single command (well, combined with the filter pandoc-citeproc, which may be needed in addition, two commands) -- which we could even put into an AppImage easily, if upstream doesn't do it by themselves).

[KurtPfeifle]

More re. "Definition of Done":

• Define a series of tests. Make them run automatically as far as possible, use Travis and similar tools wherever we can.
  • Before a release can happen, this series of tests has to be passed.
  • for source code: use linting tools, use a common formatting style (whitespace, indents, tabs vs. spaces, etc.), use a source code formatter to ensure that.
    ^{(I know something is running already for each commit, when Travis is triggered...)}
  • for binaries produced by Travis: after each successful build also run some automatic testing (like: create AppImages of well-defined inputs, compare outputs with previous ones; see if auto-update still works; etc.)
• Define a series of Live ISO systems, run tests on them:
  • A set of AppImages have to run with identical (or better) results than the previous run (no regressions)
  • Make it automatic wherever possible.
  • Have also humans run these AppImages, look at a computer screen to see if everything is Ok. Only if humans "sign off" all tests, the release can happen. (Or, whatever has failed has to be reported in the release notes.)
• Prepare a "Multi-ISO-USB" image or similar which can be used by volunteer testers.
• Write a short tutorial "How to test AppImages".

[probonopd]

ReST/Sphinx is a whole different beast for me. I'm currently not willing to put in the effort to learn all the fine details of ReST (when I know my way around Markdown already)

Same here...

[TheAssassin]

ReStructured Text isn't really any more complex than Markdown, when limiting oneself to the feature set Markdown provides. It can get complex, yes, but only when using stuff you wouldn't normally use. Before claiming that a lot of details had to be learned to get going, just check it out yourself. Like with Markdown, I'm pretty sure you wouldn't start with the tutorial, and instead "just do stuff" and look up whatever you need when there's problems.

Also, the biggest plus for me is the generation of man pages from reST, which can also just be translated to HTML from the same file. Man pages' format is pretty complex and complicated, and I don't like that at all, to me man pages are unmaintainable, and the effort of learning how to work with them is a lot bigger than transitioning from Markdown to reST.

[KurtPfeifle]

@TheAssassin:

"the biggest plus for me is the generation of man pages from reST, which can also just be translated to HTML from the same file."

If you properly had read my comments, you'd have seen that Markdown/Pandoc can do the same. And more. The downside of Markdown is, that it's not as "expressive" as ReST (but in my opinion it comes pretty close).

But you seem to agree that we do NOT need all the bells and whistles of ReST? That Markdown can do enough for our purposes?

"Man pages' format is pretty complex and complicated, and I don't like that at all, to me man pages are unmaintainable, and the effort of learning how to work with them is a lot bigger than transitioning from Markdown to reST."

I agree.

NOBODY proposed to write + maintain manpages in groff. We can do it in Markdown and convert to man/groff with the help of Pandoc. See also the man page example (no. 10).

BTW, Pandoc developers eat their own dog food too: Pandoc's man page is converted from Markdown to groff by Pandoc, and you also get a HTML version for it from the same Markdown source. Also, they seem to have a good "Definition of Done", because their MANUAL.txt is always up to date with the code they release.

[TheAssassin]

But you seem to agree that we do NOT need all the bells and whistles of ReST? That Markdown can do enough for our purposes?

@KurtPfeifle no, that's not my argument. My argument is that reST isn't much more complicated, but worth the change when going for Sphinx. The man page was just an example. HTML pages generated from pandoc are just pretty ugly, and adding a page ToC tree etc. isn't really possible with just pandoc (unless done manually in the pages, which means there's an additional maintenance overhead). We have a lot more documents than a man page to manage, and we need some structure in that. E.g., all the "How to bundle XYZ" pages should get their own category, etc.

With sphinx, that's a really easy task, and a lot of projects love it for that purpose, not only Python based ones. Sphinx has a huge user base (readthedocs for example is in the top 1500 websites worldwide, not just for developers), and there's a huge ecosystem and user base. There must be a reason why people use those systems. JavaScript based whole page text search, good standard themes, easy to compile and deploy (pure HTML), ...

Check out http://www.sphinx-doc.org/en/stable/examples.html and http://www.sphinx-doc.org/en/stable/tutorial.html (especially http://www.sphinx-doc.org/en/stable/rest.html#rst-primer, where it links to).

[KurtPfeifle]

@TheAssassin:

"sphinx [...] a lot of projects love it"

This detail is off-topic here. Please open a new issue for discussion of "tooling framework for writing documentation". I'll move my comments on that topic over there then and delete the ones here.

Stick to the more general "Definition of Done" in this thread. Thx.

[probonopd]

Indeed this issue is about having a DoD. Let's discuss the pros and cons of documentation methods in the other issue.

[azubieta]

It seems that this issue is mostly fulfilled, now we have a sphinx generated documentation and several unit tests. So can we close it?

[probonopd]

Do we have a "Definition of Done", as @KurtPfeifle requested? Where does it live?

[TheAssassin]

Do we need one? I don't think so. I will not write any man pages or anything similarly ugly, especially since I wrote some really nice guides on https://docs.appimage.org.

[probonopd]

This ticket has somewhat deviated from the original point,

Start to write a "Definition of Done". Then make it a guideline for releases.

According to https://www.agilealliance.org/glossary/definition-of-done/.

The team agrees on, and displays prominently somewhere in the team room, a list of criteria which must be met before a product increment "often a user story" is considered "done". Failure to meet these criteria at the end of a sprint normally implies that the work should not be counted toward that sprint's velocity.

It might include

• Code is in a PR
• Code has been reviewed positively by at least 1 other team member
• Code builds "green"
• PR contains updates to docs.appimage.org to reflect the new code
• We are "eating our own dogfood"; e.g., tests are updated etc.