Re: [darktable-dev] Re: Introducing dtdocs
On 10/19/20 12:12 AM, juli...@i2pmail.org wrote: There's a saying, "Sorry I didn't have time to write less." :) Indeed that is true! Glad you see the need. About the choice between Hugo or Jekyll, The choice is Hugo, Jekyll was not a consideration. I realize that some may like the speed of Hugo, but Jekyll does have incremental builds (I read that Hugo doesn't have that). In my experience working on sites with thousands of pages, by using the incremental build tag and limiting the number of languages on my local end, I would have a site I can re-test in a second or two. Jekyll needs incremental builds because ruby is slow as hell. If you want to take a look at some benchmarks: https://forestry.io/blog/hugo-vs-jekyll-benchmark/ Hugo doesn't need incremental builds, because it is fast. Hugo is written in Go also. That might be obvious from the name, Hu"go", but it probably isn't to most. So I suppose those who might want to do the documentation would need to access whether they want to use a Go binary over Ruby. The Go binary is way easier. You can download the binary directly from the hugo project, it has almost everything you need. The only other dependency is yarn to grab some NPM packages. I started on Jekyll, then moved to middleman becaue Jekyll focused too much on blogging, then eventually to Hugo when ruby proved to be too brittle and too much upkeep. You can observe a similar problem with python and the darktable.org website, which still uses pelican from python 2.7. -mica J On 2020-10-19 02:44 UTC Mica Semrick wrote: Hey Torsten, Minimalism is a basic tenant of technical writing. We should strive to convey the "thing" in question using the fewest words and image to (1) reduce the maintenance overhead and (2) more words/images generally do not make the "thing" clearer, in fact, quite the opposite. It often muddies the picture. The current documentation has a colloquial verbosity to it that (I feel) doesn't enhance the understanding of the reader. Similarly, there are images that don't enhance the readers understand either, for instance in the current documentation there is a image of every since module just ahead of the textual description of that module. In the new docs, we've split out module references into their own section and we assume you have darktable open in front of you (or you know what a module generally looks like) and thus we omit the image. If there are specific instances where you think not enough is written, you are encouraged to open an issue. Hope that makes sense. Hey Torsten, Minimalism is a basic tenant of technical writing. We should strive to convey the "thing" in question using the fewest words and image to (1) reduce the maintenance overhead and (2) more words/images generally do not make the "thing" clearer, in fact, quite the opposite. It often muddies the picture. The current documentation has a colloquial verbosity to it that (I feel) doesn't enhance the understanding of the reader. Similarly, there are images that don't enha ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Re: Introducing dtdocs
This is great. I'm relatively new Darktable but felt the need to refine the copy. Reducing written word down to its core parts does take time. There's a saying, "Sorry I didn't have time to write less." :) About the choice between Hugo or Jekyll, I realize that some may like the speed of Hugo, but Jekyll does have incremental builds (I read that Hugo doesn't have that). In my experience working on sites with thousands of pages, by using the incremental build tag and limiting the number of languages on my local end, I would have a site I can re-test in a second or two. Hugo is written in Go also. That might be obvious from the name, Hu"go", but it probably isn't to most. So I suppose those who might want to do the documentation would need to access whether they want to use a Go binary over Ruby. J On 2020-10-19 02:44 UTC Mica Semrick wrote: > Hey Torsten, > > Minimalism is a basic tenant of technical writing. We should strive to > convey the "thing" in question using the fewest words and image to (1) > reduce the maintenance overhead and (2) more words/images generally do > not make the "thing" clearer, in fact, quite the opposite. It often > muddies the picture. > > The current documentation has a colloquial verbosity to it that (I feel) > doesn't enhance the understanding of the reader. Similarly, there are > images that don't enhance the readers understand either, for instance in > the current documentation there is a image of every since module just > ahead of the textual description of that module. In the new docs, we've > split out module references into their own section and we assume you > have darktable open in front of you (or you know what a module generally > looks like) and thus we omit the image. > > If there are specific instances where you think not enough is written, > you are encouraged to open an issue. > > Hope that makes sense. > Hey Torsten, > > Minimalism is a basic tenant of technical writing. We should strive to > convey the "thing" in question using the fewest words and image to (1) > reduce the maintenance overhead and (2) more words/images generally do > not make the "thing" clearer, in fact, quite the opposite. It often > muddies the picture. > > The current documentation has a colloquial verbosity to it that (I feel) > doesn't enhance the understanding of the reader. Similarly, there are > images that don't enha ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Re: Introducing dtdocs
Hey Torsten, Minimalism is a basic tenant of technical writing. We should strive to convey the "thing" in question using the fewest words and image to (1) reduce the maintenance overhead and (2) more words/images generally do not make the "thing" clearer, in fact, quite the opposite. It often muddies the picture. The current documentation has a colloquial verbosity to it that (I feel) doesn't enhance the understanding of the reader. Similarly, there are images that don't enhance the readers understand either, for instance in the current documentation there is a image of every since module just ahead of the textual description of that module. In the new docs, we've split out module references into their own section and we assume you have darktable open in front of you (or you know what a module generally looks like) and thus we omit the image. If there are specific instances where you think not enough is written, you are encouraged to open an issue. Hope that makes sense. -mica On 10/18/20 7:18 PM, Torsten Bronger wrote: Hallöchen! A question from a prospective reader rather than author: Why do you want to keep the number of words and images to a minimum? FWIW, I find both very helpful when reading about complex matters. Regards, Torsten. ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
