[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Four kinds of documentation

On Mon, Sep 28, 2020 at 10:54:58PM -0500, jathan wrote:
> On 26/09/2020 17:50, Phil Morrell wrote:
> > https://documentation.divio.com/introduction/
> > 
> > Hi, sorry for the drive-by contribution,
> Thank you for sharing that useful link and for your point about
> documentation and explanation contents. How will you push instructors to
> encourage explanation videos with the features you mention

By sharing the link in this email. I can't really be more helpful here,
but I'm hoping that as the Debian Academy concept/team pick up steam it
will come up with some labelling or organisation method for the content
as a whole so will itself need some way of sharing best practices with

> which are the "first two types" they could find natural to produce
> please?

This I can expand on :), the Four kinds of documentation according to
this site are structured like this (column is "useful while doing X"):

|             | Studying    | Working       |
| Practical   | Tutorials   | How-to guides |
| Theoretical | Explanation | Reference     |

The "first two types" are the Practical ones, I'm arguing this is the
natural form to produce because it's most prevalent across the internet,
focussing on getting as much done in as little time as possible.

By sharing this link I hope to highlight the missing piece especially
useful while studying (via Debian Academy) that helps convey theoretical
understanding and IME commonly comes from mentors in Debian. i.e. our
wiki and dev-ref try to be tool agnostic, describing how you *can*
package for debian, but there's not a lot saying how you *should*.

Attachment: signature.asc
Description: PGP signature

Reply to: