Follow

open source software development advice 

If you do a thing in an open source project, and you have a hard time doing it because it's not documented, after you finish doing the thing... document it. If the project has a wiki, put it in the wiki. If it has a docs repo you can write to, put it there. Or at least blog about it so search engines can index it.

Please don't leave the solution to languish in a chat log somewhere.

open source software development advice 

@darius

tired: literate programming
wired: literate program operations

(this inspired by my own journey to and back away from literate programming)

open source software development advice 

@darius I haven't been sharing because they're intermingled with personal notes but I've been even just logging as I read technical documentation; and I got good feedback on when i shared having done that for the first few sections of the guix manual.

A lot of people are critical of literate programming because of the overhead it adds to design but then never revisit it for operating what they made and I think that's a missed opportunity.

re: open source software development advice 

@darius Or at least if you find the solution while asking on chat/forum/mailing, tell the solution.
Because even if you wouldn't other people could then document it properly.

open source software development advice 

@darius

Follow-on -> If you spend vast amounts of time developing a piece of sofware, and decide to opensource it, and put it up on sr.ht or Gitlab or Github or wherever, consider putting 3/4 of an hour into writing clear, plain english instructions as to how to install it that do not require an esoteric knowledge of ruby, or python or whatever to install it.
Otherwise your'e losing at least 60% of your potential base.

open source software development advice 

@dublinux @darius Yes! There was one tool I spent 2-3 days trying to get installed before giving up.

open source software development advice 

@dublinux @darius
Note: a black-box docker container doesn't count as an installation method.

re: open source software development advice 

@darius this also goes for reverse-engineering APIs that don't have documentation

document what you find

because it's a lot easier to find differences in specifications than it is to reverse engineer two opaque APIs when you inevitably need to fix it

open source software development advice 

@darius best to leave all of the notes in tickets marked #wontfix

open source software development advice 

@darius i

am

so

guilty

of

this

😔

open source software development advice 

@darius

I'd even suggest to not wait until "after you finish doing the thing", but allready start with documenting the problem

("I want to do [this], but it's hards as I don't know [think], I allready tried [that] .... " )

That way, you have most of the documentation-work allready done, and a "[thing] solved it!" is easily added!

re: open source software development advice 

@darius Where's the fun in that?!?!

open source software development advice 

@darius
Interviewer: What's the worst thing you've done as a programmer?

Programmer: No comment.

open source software development advice 

@darius @ramsey

https://m.xkcd.com/979/

> All long help threads should have a sticky globally-editable post at the top saying 'DEAR PEOPLE FROM THE FUTURE: Here's what we've figured out so far ...'

Sign in to participate in the conversation
Friend Camp

Hometown is adapted from Mastodon, a decentralized social network with no ads, no corporate surveillance, and ethical design.