Re: Documentation Updating

[Nate Bargmann]

* On 2022 23 Feb 10:46 -0600, Nick Craig-Wood wrote:
> As a new user (new to both contesting and tlf) I was thinking about helping
> with the docs too.

Welcome!

> I think it would be good for the project to have nice looking online docs.
> In another project I'm involved in (rclone) we use markdown for the docs and
> convert that into man pages and the website.

Forgive me!  I have become somewhat of a man page purist in recent
years.

While I understand the utility of a single source file for all
documentation, the fact is that while man pages are documentation they
exist in a different problem domain than Web pages or a PDF manual.  The
existing man page is a pretty good reference even if it is a bit
verbose, though that is a trend for many man pages these days.

The HTML pages, though old, have the benefit of the screenshots of the
Tlf UI.  IMHO, Markdown is an ideal source format for the HTML and PDF
documentation simply because it handles inline images in those formats.
The way one approaches writing a manual with images seems much different
than writing for the man page reference format where images cannot be
used inline.

> The website is the primary documentation method, but all the
> information is in the man page too. I like this way of working because
> there is only one source for the documentation - the markdown files -
> and everything else is built from there. I could certainly help with
> this if people thought it was a good idea. I'm not much of a technical
> writer, but I'm a better software developer ;-)

As I see it, the man page should be a reference that serves as a memory
refresher for configuration and operation commands.  The HTML/PDF should
be a more conversational manual that makes use of the images and links.
The man page can be output to HTML as well and included if desired in an
HTML/PDF manual.

These are just my thoughts.  The rest of the project members likely have
differing opinions!  :-)

> I just want to say thank you to all the developers of tlf - I know how
> hard Open Source software is!

You're welcome!

I am only a hobbyist in the software realm so I don't know whether this
is more difficult than closed source software or not.  I do know that
collaboration is fun and satisfying.

73, Nate

-- 
"The optimist proclaims that we live in the best of all
possible worlds.  The pessimist fears this is true."
Web: https://www.n0nb.us
Projects: https://github.com/N0NB
GPG fingerprint: 82D6 4F6B 0E67 CD41 F689 BBA6 FB2C 5130 D55A 8819

signature.asc
Description: PGP signature