News for hackers. Stuff that matters.
Re:GitHub Actions is my new favorite free programming tool [... by ReidZB on Thursday December 19, 2019 @02:45PM (#21838473)
I read an article[0] on HN[1] recently — it talks about the different types of documentation. To quote it directly:

"Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances - so software usually needs them all."

I agreed with its premise — I've found things that only have "story format" docs (i.e. explanation / how-to guides) to be really frustrating. On the other hand, if all that's available is a deep and highly particular technical reference, it's really difficult to get started sometimes.

[0] https://www.divio.com/blog/documentation/

[1] https://news.ycombinator.com/item?id=21289832

Re:GitHub Actions is my new favorite free programming tool [... by Wowfunhappy on Thursday December 19, 2019 @03:10PM (#21838736)
What is the difference between a tutorial and a how-to guide?
Re:GitHub Actions is my new favorite free programming tool [... by keithnz on Thursday December 19, 2019 @04:44PM (#21839644)
if you read the link he gave, it has a really good description of each...

but to summarize...

A tutorial: - is learning-oriented - allows the newcomer to get started - is a lesson

A how-to guide: - is goal-oriented - shows how to solve a specific problem - is a series of steps

Re:GitHub Actions is my new favorite free programming tool [... by Already__Taken on Friday December 20, 2019 @06:53AM (#21843455)
And as an example, Don't list how to install node.js, npm packages and ENV settings in your HAPI server tutorial
Re:GitHub Actions is my new favorite free programming tool [... by jwhitlark on Thursday December 19, 2019 @03:18PM (#21838793)
Level of previous knowledge assumed, tutorials tend to be more "starting from zero", and scope, guides tend to have a narrower focus.
Re:GitHub Actions is my new favorite free programming tool [... by 77544cec on Thursday December 19, 2019 @04:51PM (#21839689)
A tutorial is to an integration test what a how-to guide is to a unit test.
Re:GitHub Actions is my new favorite free programming tool [... by tartoran on Thursday December 19, 2019 @11:07PM (#21841645)
Think of how tos as recipes for different scenarios