I see a lot of open source software projects that do not do a good job of describing themselves.

It's okay. There's nothing shameful about that.

Most programmers aren't writers.

Just like most writers aren't programmers.

I can't code to save my life, but I can write some killer copy and content.

Know of any open source projects that need copy written?

I want to contribute.

> Most programmers aren't writers.

I'd like to engage in a philosophical discussion about why they certainly are writers, and why good programmers must be able to write.

But I'll just thank you for your will to contribute and encourage you to do it, because it is really valuable.

@ekaitz_zarraga Well I guess literally they "write code" so they are writers. Maybe I should find a better noun or more specific adjective.

@estoricru @ekaitz_zarraga linguistics has a high correlation with programming. linguists are better programmers


> #linguists are better #programmers

It's an hypothesis, but empirically, I can think of a few notable programmers with a background in #philosophy. No linguists though, not even Prof. #Chomsky.

Programming languages can be studied and analysed in linguistic terms, but languages are tools not the result itself.

@estoricru @ekaitz_zarraga


Are we talking about the perpetrator of #Perl? I thought you were trying to reinforce your point, not refute it. 🤷

The (random) paper that you mention talks about learning to program, it says nothing about code quality and it says nothing about #linguists either, in the sense of scientific study and analysis of languages.

Empirically speaking, that multilingual people are more adept at programming is a plausible hypothesis, though.

@estoricru @ekaitz_zarraga

@0 @estoricru @ekaitz_zarraga Perl was the backbone of the internet through the 90s, when pretty much every website you came into contact with was run in some part by Perl, so, yes.

It's not really a random paper, it explicitly states that someone being a linguist is a better predictor of how well they will pick up programming.

Also, both of those comments sound reasonably rude or designed in some way to provoke, is that not against your rules of engagement?

Doing an actual code quality survey is going to be impossible unless you have a codebase purely written by linguists. Or you have an index of git blames with logged bugs.

@alexandria @0
> Perl was the backbone of the internet through the 90s, when pretty much every website you came into contact with was run in some part by Perl, so, yes

Not only that, Perl have been very influential and is a great language. We may or may not like it, but underestimating stuff because of our opinion instead of the technical facts or achievements just because it's kind of accepted to diss on it it's just absurd.

@alexandria @0 This pisses me off so hard.
Not because of what you @0 did, it's just a general feeling. There are projects like Perl or C++ that is kind of accepted to insult because some part of the programming community wanted to follow the trend of a couple of motherfuckers that can't shut their fucking mouth.
It's ok to dislike something, but it's not ok to throw some shit in a discussion when people is talking about facts. Let's be adults.

@alexandria @0
Not saying it's what you did here. I think you just played the easy card: let's say perl is shit, because "everybody" says that.
I was expecting something else, honestly. But you are not the one to blame.

I'm sorry, this triggered me.
I apologize if it was rude.
I didn't want to make it personal. It's just a general feeling and this conversation reminded me of it.

@estoricru @ekaitz_zarraga Not even coding. If a developer can’t write, they can’t communicate effectively with other developers or project stakeholders. Writing is huge.

@jamesgecko @ekaitz_zarraga The burden of successful communication is on the communicator so this is my fault but I didn't mean it that literally.


> The burden of successful communication is on the communicator

One begs to differ.

Communication is a shared activity. Asymmetric, yes, but it necessitates an active role from all parties.

And now to be of some actual use, projects that I think could benefit of, and deserve, better docs:

* #Conversation #XMPP messenger
* #KDE #Calligra #Plan

I'll add more as they come to me.

@jamesgecko @ekaitz_zarraga

@estoricru @ekaitz_zarraga Eh, we understood what you meant, tbh.

Coders are a type of writer. The problem is that coders write in a language that's very different from what humans tend to read.

The different structures make it hard to translate between them and the more human counterparts.

@eletrotupi @ekaitz_zarraga the problem with having documentation that is not code is that you have two sources of truth, and no automatiac way to verify that they're in sync. Therefore, they get desync over time.

@wolf480pl @eletrotupi @ekaitz_zarraga They always tend to desync a bit but with being careful about it, it doesn't desyncs that much. (You changed/added/removed some interface or behaviour? Update the documentation. Also put them in the same repository.)

And there is a bunch of tools to have documentation being next to the code(javadoc, doxygen, …) or with the skeleton generated from it (swagger/OpenAPI).

@lanodan @eletrotupi @ekaitz_zarraga
Yes, documentation autogenerated from code comments solves this problem for low-level API docs. But what about high-level overviews?

@wolf480pl @eletrotupi @ekaitz_zarraga Like for the user interfaces? (API being already quite solved with OpenAPI stuff)

@lanodan @eletrotupi @ekaitz_zarraga no, like for the architecture of the whole thing... for the concepts it operates on... for how the parts fit together and achieve a bigger goal

@lanodan @eletrotupi @ekaitz_zarraga though docs for the user interface may be hard as well, maybe even harder

@wolf480pl @eletrotupi @ekaitz_zarraga They're not so hard actually.

Like most game will document their controls or show them in settings, why can't non-games usually do this as well?

As for the graphical part I think this would be solved by making layout builders actually usable in toolkits/frameworks and being able to extract at least a skeleton from them like with OpenAPI.


There was a short essay from the late Umberto #Eco on #software documentation. I think it might have been in il secondo diario minimo, and it should be compulsory reading for anyone thinking of writing documentation of any kind.

@eletrotupi @ekaitz_zarraga @wolf480pl

@wolf480pl @eletrotupi @ekaitz_zarraga To me that belongs to stuff like whitepapers with stating the version it's based on.
And I don't really see this as documentation, more like presentation (~lecture).

It should be transparent into the documentation but I don't think it should actually be into it.


Depends what kind of docs we're talking about and, to some extent, how careful you are to write them in such a way that they stay sufficiently accurate as the system evolves.

E.g., stay away from screenshots unless you have an actual and generous budget for a doc team.

@eletrotupi @ekaitz_zarraga

@estoricru we always enjoy contributions!

Especially with the rebranding currently going on, it can't hurt to have someone external/unbiased to have a look at the descriptions:

Let us know if you need any help :)


@estoricru In the majority of cases when I find the homepage of an unknown open source project I go to Wikipedia trying to understand what they do.

Part of the problem is also that they want their page to look nice and modern, rather than clear.

@VictorVenema Yes exactly!! I want to help solve that problem

@estoricru same here. I'd love to help with documentation & descriptions (& may I say marketing? because that's what I'll do. Marketing.)

@lexane You can say marketing. It's what I do, too.

People don't understand everyone is a marketer. We are all marketing something. Sometimes it's ourselves. Sometimes it's our ideals.

At the end of the day, we're all trying to "sell" something. The exchange may not be currency, but it's still an exchange.

@lexane @estoricru
Think CalyxOS from the Calyx Institute needs stuff writing for their new website (not live yet)

Check them out
(Also check the team and directors pages)
#calyxos on freenode

I met Nick Merrill when he was passing through the Silicon Valley on a trip to try and get funding for his non-profit projects. His foundation could use some TLC in the marketing end of things. From my perspective, he earnestly means to do right by his users, and will go to court to protect their interests:

@lexane @estoricru

@estoricru !! I've been trying to work on the opensimulator wiki for a while, but tbh I'm not sure what a copy is (I'm not a writer! lmao)
But it certainly could use a hell of a lot of writing, and I know that I'm really bad at that !
If you want to check it out, it's
I'm trying to make an improved UI for the whole thing lol

@estoricru I've been wanting to market my "Rhapsode" and "Haphaestus" browser (engines) to a less technical audience, but I've been feeling blocked. Can you help?

I'm hoping to crowdfund Haphaestus sometime soon...

@estoricru Most projects can use some help ( even if it's just spreading the load )

Look at projects you use and see if there's improvement you'd like to see at the person using the software

Sometimes I just submit small grammar correction bug reports or pull requests

If you want to help with a conference, I chair the promo committee for SeaGL, we can use help with our blog posts

All my projects are in desperate need of an editor.

@paul Fill out this form. I do pro-bono work for creative commons / open source stuff but I still need to treat you like a paying client because of tax reasons (this is actually a benefit to you as're not treated like a side project)

Thanks Garrett. It's a bit too soon to bring on someone in such a formal capacity, but I've saved your form link.

Several of my more recent programs are written in a style known as literate programming. Basically, I write the words describing the program structure in detail, then inject code in between the words.

At some point, it'd be really interesting to get a real writer to help tighten things up.

@estoricru everything we do basically(orca, ronin, left, dotgrid, etc).

@neauoire Fill out this form. I do pro-bono work for creative commons / open source stuff but I still need to treat you like a paying client because of tax reasons (this is actually a benefit to you as're not treated like a side project)

@estoricru it's a bit complicated because to be able to efficiently write about the esoteric tool, you have to be familiar with it yourself, but then to become familiar with it we would need to have good documentation. It's a bit of a vicious circle.

@neauoire I've done technical writing before, too ;) We'll figure something out; I promise.

@zee Fill out this form. I do pro-bono work for creative commons / open source stuff but I still need to treat you like a paying client because of tax reasons (this is actually a benefit to you as're not treated like a side project)

@estoricru Done! Most of our maintainers/contributors run their contributions through their own S-Corps or LLCs, so we’re used to such things :).

Sign in to participate in the conversation

A bunch of technomancers in the fediverse. Keep it fairly clean please. This arcology is for all who wash up upon it's digital shore.