1. 5

    Admit it. If you browse around you will realize that the best documented projects you find never provide that docs generated directly from code.

    Is this saying that you shouldn’t use Javadoc or pydoc or “cargo doc”, where the documentation is located in the source files? So, from the previous point, it’s essential that docs live in the same repo as the code, but not the same files as the code? Seems like a pretty extreme position relative to the justification.

    1. 18

      As a concrete example, Python’s official documentation is built using the Sphinx tool, and Sphinx supports extracting documentation from Python source files, but Python’s standard library documentation does not use it - the standard library does include docstrings, but they’re not the documentation displayed in the Standard Library Reference. Partially that’s because Python had standard library documentation before such automatic-documentation tools existed, but it’s also because the best way to organise a codebase is not necessarily the best way to explain it to a human.

      As another example in the other direction: Rust libraries sometimes include dummy modules containing no code, just to have a place to put documentation that’s not strictly bound to the organisation of the code, since cargo doc can only generate documentation from code.

      There’s definitely a place for documentation extracted from code, in manpage-style terse reference material, but good documentation is not just the concatenation of small documentation chunks.

      1. 1

        Ah, I was thinking of smaller libraries, where you can reasonably fit everything but the reference part of the documentation on one (possibly big) page. Agreed that docs-from-code tools aren’t appropriate for big projects, where you need many separate pages of non-reference docs.

      2. 10

        There’s definitely a place for documentation extracted from code, in manpage-style terse reference material, but good documentation is not just the concatenation of small documentation chunks.

        Can’t agree enough with this. Just to attempt to paint the picture a bit more for people reading this and disagreeing. Make sure you are thinking about the complete and exhaustive definition of ‘docs’. Surely you can get the basic API or stdlib with method arity and expected types and such, but for howtos and walkthroughs and the whole gamut it’s going to take some effort. And that effort is going to take good old fashioned work by technical folks who also write well.

        It’s taken me a long time to properly understand Go given that ‘the docs’ were for a long time just this and lacked any sort of tutorials or other guides. There’s been so much amazing improvement here and bravo to everyone who has contributed.

        On a personal note, the Stripe docs are also a great example of this. I cannot possibly explain the amount of effort or care that goes into them. Having written a handful of them myself, it’s very much “a lot of effort went into making this effortless” sort of work.

        1. 8

          Yeah I hard disagree with that. The elixir ecosystem has amazing docs and docs are colocated with source by default for all projects, and use the same documentation system as the language.

          1. 2

            Relevant links:

          2. 5

            The entire D standard library documentation is generated from source code. Unittests are automatically included as examples. It’s searchable, cross-linked and generally nice to use. So yeah, I think this is just an instance of having seen too many bad examples of code-based docs and not enough good ones.

            When documentation is extracted from code in a language where that is supported well, it doesn’t look like “documentation extracted from code”, it just looks like documentation.

            1. 4

              Check out Four Kinds of Documentation. Generated documentation from code comments is great for reference docs, but usually isn’t a great way to put together tutorials or explain broader concepts.

              It’s not that documentation generation is bad, just that it’s insufficient.

              1. 2

                Maybe the author is thinking about documentation which has no real input from the developer. Like an automated list of functions and arguments needed with no other contextual text.

                1. 1

                  I saw this earlier this week, maybe on Twitter? How did you come to find this and what do you think?

                  1. 1

                    I always liked the author (from his past column on The Guardian). I’ve already finished the book, and I like it a lot. Not much I didn’t know there, but the way he writes makes it a fun read.

                1. 5

                  I’m going through Writing an Interpreter In Go (https://interpreterbook.com/). I’m looking forward to learning how the author thinks and structures an Interpreter. Eventually, I’ll get to his next book: Writing a Compiler.

                  1. 3

                    I’m 3/4 through and I’ve really really enjoyed it so far.

                    One thing I found useful albeit tedious at first was typing out every file as I read it. I really wanted to internalize as best I could the content. Then as new concepts were introduced I tried to implement them before reading the next code snippet shown in the chapter.

                    1. 2

                      Then as new concepts were introduced I tried to implement them before reading the next code snippet shown in the chapter.

                      Great idea!

                  1. 1

                    If I wasn’t so invested in the Apple ecosystem, Elementary would be the obvious choice for me as the distro I’d want to run on my main computing machine.

                    I’m hoping it’s still around so it can be the first OS I can set up for my kiddo.

                    1. 3

                      This was wholesome as f*ck. I watched the whole thing mesmerized. Thank you for sharing this!

                      1. 1

                        I definitely need to get Prometheus up and running, sounds very flexible and I’d like to get dashboards set up at some point. I went down this same project a couple months ago, and found that you don’t need so much edge compute per the Raspberry Pis. The Python script in this post could be reduced a fair bit to just listening via Bluetooth for devices broadcasting like the LYWSD03MMC via custom firmware.

                        https://github.com/atc1441/ATC_MiThermometer https://blog.dalanmiller.com/home-assistant-with-ble-monitors/

                        1. 5

                          Small nit but the homepage taking hostage of scroll drives me mad.

                          1. 3

                            A captivating story. I feel like he would most certainly be in jail today and/or Apple has since upped the security or permissions on the machines in stores today.

                            1. 1

                              Thank you all for making Lobs one of my favorite places on the web.

                              1. 5

                                Are there release notes?

                                  1. 3

                                    Attending a sleep school/program with my young < 1 y/o son.

                                    At some point in all our lives we learned how to sleep. It’s absolutely wild.

                                    1. 2

                                      Most of my software productivity outside of work is for a community for software professionals called Code & Supply that I co-run with a friend.

                                      1. 1

                                        Hey! Curious if there’s still intention to upload videos from the first Abstractions conference?

                                        1. 1

                                          Unfortunately, no. There’s only one video that wasn’t affected by the severe technical problems that our AV vendor didn’t catch before it was too late: Anatomy of a Great Pull Request by Sean Griffin. Everything else had bad video, bad audio, or both.

                                      1. 4

                                        Is passlist and blocklist usage really so hard?

                                        1. 24

                                          Is it really so hard to realize many people are simply unaware of the controversy?

                                          Is it really so hard to realize people are creatures of habit and do not even realize they are using non-preferred nomenclature?

                                          Is it really so hard to realize that scolding them like this is counterproductive, because they will automatically become defensive?

                                          I could have phrased this nicer and more constructive. Could you?

                                          1. 16

                                            100% – I’m leaving my comment up as it was a silly and unconstructive knee jerk reaction. Thank you.

                                          2. 4

                                            This page is at least 9 years old; it was submitted to HN in 2011.

                                          1. 15

                                            For short and ephemeral text and images, check out the “note to self” feature of Signal. It appears as the name of one of your contacts. This requires your devices be linked, but approximates the lazy email-it-to-yourself approach with an added layer of reasonable privacy.

                                            1. 3

                                              Signal is my usual go to. What I’m sending is often long untypable passwords, so I keep the disapearing messages set to 5 minutes as well.

                                              1. 2

                                                I use this feature all the time. It’s great for sending non-url things to other devices. For URL things, I uuse Firefox’s “Send to Device” function that works when you have browser sync enabled.

                                                Edit to Add: Slightly OT, in F-Droid there is an app called Exif-Scrambler. It’s a wonderful tool for scrubbing metadata out of pictures. Share to Exif-Scrambler, then E-S will scrub metadata and present you with another share option, at which point I use Note to Self on Signal.

                                                1. 2

                                                  Yep! I’ve been using this too but it felt clunky still.

                                                  1. 1

                                                    How so? What would you change?

                                                    1. 1

                                                      I don’t think there’s much I could change but it isn’t as seamless as iOS Universal Clipboard or Airdrop

                                                  2. 1

                                                    Does it bother you that Signal for desktop is not encrypted?

                                                    1. 1

                                                      I assume you mean “not encrypted at rest”? Doesn’t bother me personally (if you control my user account you have ~everything anyways).

                                                  1. 5

                                                    I took a handful of extremely good classes in grad school that were life-changing for me … specifically an Advanced Computer Security seminar where I met people and did projects that helped me get where I am today. However, 80% of it was a waste, just classes I didn’t really care about that were required for the program. I’d find those couple of specific classes that are really important to you, excel in them, and don’t worry about a whole degree.

                                                    (I went during the last recession, when the best jobs I could get paid surprisingly poorly, so the opportunity cost was relatively low. Today things are different!)

                                                    Sadly, there’s good evidence that companies negatively select against MS degree holders: https://blog.alinelerner.com/how-different-is-a-b-s-in-computer-science-from-a-m-s-in-computer-science-when-it-comes-to-recruiting .

                                                    1. 3

                                                      I have felt the same about my own university experience and have heard others say similar things too. Effectively to the tune of “one or a handful of classes were life changing but the rest wasn’t really useful”. The only issue is, how would you have taken that class if it weren’t for the required curriculum of the degree program? I keep coming back to the question of “How would we discover such life changing courses on their own and outside of academia?”

                                                      1. 7

                                                        The world is full of nonsense research and papers; developing effective techniques for finding the gold nuggets is a requirement for success in any field.

                                                    1. 1

                                                      https://www.dalanmiller.com/

                                                      Pretty chill 🧘🏻‍♂️

                                                      1. 1

                                                        You can feel the surf dude smiling at you.

                                                        1. 1

                                                          It’s quite professional. Articles themselves resemble Medium style, but since it has no annoying popup things it feels cleaner than Medium. Well done.

                                                        1. 1

                                                          @djsumdog

                                                          • I as well tried using Alpine for my NAS but eventually switched to Ubuntu Server. What packages did you find that you ended up using?
                                                          • Why ZFS over anything else?
                                                          • What’s your methodology around drive prices? Is there a certain cents per GB that you wait for?
                                                          • Does your NAS do anything other than be an NFS host? NFSv3 or v4?
                                                          1. 1

                                                            I don’t have very many packages installed. The major ones are: cryptsetup (luks), efibootmgr, fish (my favourite shell), gptfdisk, grub-efi, htop, iproute2 (busybox ip is limited), lsblk (for block UUIDs), lvm2, nfs-utils, smartmontools, vim, zfs, util-linux (again, to replace busybox tools) .. a few others.

                                                            I tried out ZFS a few years ago and it’s been very stable. I like how it does snapshots which makes backups way easier (if you move a folder, rsync will want to delete and recreate all the files. With zfs snapshots, it will send a diff of only the metadata). Since zfs-0.8 now supports native encryption, I no longer need zfs+luks. The boot drive is still ext4+luks. I hope to have a guide on the install soon.

                                                            For drives, I just have two primary (storage-main, 18TB, storage-alt 12TB) and their backups (14TB and 10TB). I was super minimalist for a while and wanted to carry everything on just one hard drive. So I’ll usually spend more for large drives and do full backups, rather than try to do RAID + some other backup solution.

                                                            Right now it’s just NFS4. I had samba running on my old one for the Windows box and I’ll probably set that up again. I’ve been meaning to implement NFS4+krb encryption; hope to get a guide up on that soon too.

                                                          1. 4

                                                            While I think that encouraging open source contributions is really important, the tooling to support this seems broken.

                                                            A different point entirely, why are we still shipping free t-shirts around the world in 2020?

                                                            • The earth is constantly on fire.
                                                            • The shirts and logistics are at best carbon-neutral (but will inevitable still require logistics which put greenhouse gases into the air)
                                                            • Do people really need more t-shirts?
                                                            1. 3

                                                              Do people really need more t-shirts?

                                                              If no one goes crazy with implications about me being racist or something, I can probably answer - yes.

                                                              These people are often from India (or the whole IO region, including Malaysia, Indonesia, etc.), especially from rural and countryside areas which are exceptionally poor compared to their Western counterparts, but yet become “digitalized” and connected to the Web which accelerated way faster than other “quality of life” areas there, to the point there’s sometimes cheaper and easier to find the cellphone/computer and send gigabytes of data than get a regular healthy food, cloths or even clean water.

                                                              So, young people there got technology, but didn’t get the knowledge, yet due to various cultural influences and legacy they still want to prove “india stronk and superpower by 2020”. This is mostly why the Android enthusiasts community is completely trashed now (the smartphones are orders of magnitude more popular than PCs in these regions) and while other areas are also getting the “indian bit” attached, it’s not as clearly visible as for example on XDA forum.

                                                              Yet still, they must eat, drink and wear something. So when someone spotted the Hacktoberfest with giveway, everyone rushed there hoping to get free stuff which might be actually useful in their daily lives, as t-shirts are.

                                                              Many of these people don’t actually know they do something bad, because they lack the knowledge, language and basics of “development culture” yet they still are pretty much convinced about doing good and being important and valuable. We should somehow address that and at least try to understand (which is different than accepting the state) and maybe redirect them into some sort of “incubators” for OSS projects to not harm the actual upstream. And while I’m not a fan of “lowering the bar” (and I don’t want anyone to do this) it might be valuable to direct these people into (currently non-existent) places where they could grasp the dev culture and actual technical knowledge helping each other without getting in the way of anyone else, and then pick most prominent ones.

                                                              1. 2

                                                                If we don’t need t-shirts shipped around the globe maybe there should be better distribution lines? Or just get rid of globalization, period? /s

                                                                Honestly, no, the typical developer probably doesn’t need more (free) t-shirts, but after not going to conferences for a few years I think I average getting one new t-shirt per year. And the Hacktoberfest one I have is one I like.

                                                                I don’t really see a big difference to buying any sort of non-eco-whatever local brand clothing. Hacktoberfest was a niche event and I guess 2019 it saw a pretty big uptick in popularity. I still think the shipping for these few t-shirts isn’t even noticeable, compare to (nearly) free shipping for electronics stuff from china and people don’t even bother, just order single items because they’re cheaper (sometimes 10-100x) than buying them without shipping in a local store.

                                                              1. 16

                                                                Something actually good for photo management and editing..

                                                                • RAW processing must be done on the GPU, as in vkdt, but like, write it in Rust, using wgpu or something. There is a raw loader in Rust already, use it
                                                                • don’t use imgui type things for UI noooooo just use GTK please and make it look nice and simple and GNOME-ish
                                                                • what is infuriating about Lightroom and every clone is that they treat exports as fire-and-forget. If you browse the library, it re-renders from RAW all the time, maybe using some kind of cache (badly). I do want to manage the JPEGs! In fact I want to see the JPEGs most of the time but if RAW exists for a photo I want a “redevelop” button to exist of course. And the discovery of the RAW origin of the JPEG must be really “bulletproof”, no matter how I move stuff around the FS as long as it’s below the directories the software knows about.
                                                                  • conversely, software like digiKam that aims to organize all the things is usually not great at RAW.
                                                                • why does everything suck over NFS. I store photos in NFS shares, please take it into account and access everything optimally. Don’t mmap the photos. Don’t use SQLite databases that don’t work over NFS. Argh.
                                                                1. 4

                                                                  All the putative Lightroom replacements are terrible. I would happily pay what I pay to Adobe to literally anyone else for software that did the 60% of what Lightroom does that I use.

                                                                  1. 1

                                                                    Can you expand on the things in Lightroom you find most useful?

                                                                    1. 2

                                                                      Organizating, developing, importing and exporting. And I don’t do that much developing in Lightroom, but I do use Photoshop, which opens a whole other kettle of fish.

                                                                    2. 1

                                                                      Do you / others hate capture one? Seemed pretty good from my limited use but not mentioned in any of these replies.

                                                                    3. 3

                                                                      This is not the answer you want, but

                                                                      why does everything suck over NFS

                                                                      … is because NFS itself sucks.

                                                                      1. 2

                                                                        why does everything suck over NFS. I store photos in NFS shares, please take it into account and access everything optimally. Don’t mmap the photos. Don’t use SQLite databases that don’t work over NFS. Argh.

                                                                        I feel your pain!

                                                                        I’ve been continually disappointed at how poorly many Linux apps perform when run on an NFS file share.

                                                                        Also, I do not speak for my employer, but I work for the AWS EFS team and my service presents itself as an NFS file share, so we see a fair bit of customer pain around this as well.

                                                                        It surprises me how little innovation I see in the remote filesystem space these days given that we have pervasive gig speed networking growing on trees and computers so fast that the processing load of the NFS protocol is largely inconsequential for many use cases.

                                                                        1. 2

                                                                          I work in the data space and everything is moving to “the cloud” and that typically means object stores. People have wasted too much money on things like HDFS, they just want to store files somewhere and not have to think about it. (The pain that these are not really file systems is largely ignored)

                                                                          1. 1

                                                                            Yeah it sometimes surprises people how many use case really work well when implemented on a file system, especially one that has reasonable capabilities for locking and the like.

                                                                            That’s true everywhere from the back end where people are storing raw seething data all the way up to the consumer user experience where Apple tried DESPERATELY for the first decade of its life to hide the fact that there was a UNIX-ish userland behind the curtain with a bog standard traditional filesystem, and even they’ve gone back on that by providing their “Files” app and interface in recent releases.

                                                                            Files are just an incredibly useful way to think about data from just about every angle. Certainly not THE ONLY way or THE BEST way because such descriptors are pointless when talking about abstractions.

                                                                            1. 2

                                                                              In a sense, files are a reasonable (of course almost nothing is perfect, and files are not) implementation of a core and almost unavoidable notion of compartmentalisation, or a Bunch Of Stuff, together with the clearly desirable idea of using various tools on the same Bunch Of Stuff… Hard to avoid that completely!

                                                                        2. 1

                                                                          Second on every LightRoom clone being… not great. Sadly I’ve stuck with actually paying for LightRoom, but I would gladly pay $80+ one time for an adequate replacement.

                                                                          1. 1

                                                                            No, my complaints apply to Lightroom itself too — at least back when I used it, export worked exactly the same way there.

                                                                            I actually like the editing part of RawTherapee more than Lightroom :P

                                                                            1. 1

                                                                              I’m just getting started. The auto button is much better in LightRoom :’)

                                                                          2. 1

                                                                            I do want to manage the JPEGs! In fact I want to see the JPEGs most of the time but if RAW exists for a photo I want a “redevelop” button to exist of course

                                                                            You’ve probably tried it, and it has its own warts, but digikam does track the jpeg and allows you to re-import raw images. Just letting you know if you haven’t tried it before :)

                                                                            1. 1

                                                                              Have you seen Darktable? I think it covers most of your bases.

                                                                              1. 1

                                                                                Of course. The remarks about Lightroom and its clones definitely apply. Also its GPU support is incomplete and based on OpenCL – with some advanced usage of OpenCL that’s not supported by Mesa Clover (the “images” feature especially).