Slashdot:
David, can you talk a little about Write the Docs. What is Write the
Docs?

David Smatlak for Write the Docs:Write the Docs was started by a guy named Eric Holscher who created a project with two
of his colleagues, Charles Leifer and Bobby Grace called Read the Docs and Read the Docs is a repository for open source documentation.
Write the Docs came about as a result of that through the interest of so many other people in the community, not only developers, technical writers, designers, editors, just people that were interested in creating good software, better software, and documentation that goes with it. And creating both at the same time really.

Slashdot:
And to be clear, we are talking about open source software
specifically?

David:
Correct. Open source. And really for any project, Read the Docs was
created in Python they use things like Markdown and Sphinx but the
documentation is the app open source and really any kind of project
that someone wants to work on.

Slashdot:
Can we talk about what sort of projects and what sort of docs we are
talking about? What are some examples of the kind of documentation
that gets made through Write the Docs?

David:
Let’s see. Well, this year at the conference we had some people
from a newspaper come in and they wanted some help with a project
that they were developing, and we had a meeting – or writing
day -- on the first day of the conference, and they just asked
people to help. So it is very community based. We had another
application there for a password application that wanted some
feedback on the UI and some of their documentation. So we had that,
where people got involved and helped out. But really it is anything
that someone wants to work on. We have other vendors there. Mozilla
was there talking about the Mozilla developer network and showing
people how to write documentation, and edit for their site. But it
really focuses on open source.

Slashdot:
What is the significance of documentation per se? I mean how much
does that add?

David:
I think it adds a lot. It is always good to have your code
documented, if not for another developer, even for yourself, I have
heard several developers over here who say, you know, hey, six months
after I have created something, I need to go back and really look at
it, to figure out what I was doing a long time ago. I know myself I
have done that with scripting and things like that. I also think it
is important for sustainability of an application and the community
that has been built up around this. It really shows people care, and
really want to create better products.

Slashdot:
What sort of people end up getting involved with Write the Docs? Is
it mostly the developers themselves, is it people who aren’t
developers—what is the typical participant?

David:
It is both. I am not a developer myself. I am a writer, but it really
brings developers, writers, this year we had some great talks at the
conference from user experience and UI developers and people that do
QA testing on software. So it really brings a lot of different
aspects of software into the mix. We have had data librarians
aboutthat’s a really technical field. And how they use
documentation in different software in open source. So it really
brings together a vast array of people.

Slashdot:
Can you talk a little bit about the logistics of it? If somebody
says, hey, I want to, I’d like to do this, and help improve the
world’s documentation, where do you start? How do you actually
take part as a participant if you want to be part of this Write the
Docs?

David:
A great way to get started is in the meetup groups. We now have eight
meetup groups in the US in various cities—Seattle, Portland has
a very active community, San Francisco, Austin, several others, and
we even have Europe. So we have sites now in Ireland and London. And
there is a conference every year in Portland, next year it is May
22nd
through the 24th
in 2016. And then there will be a European conference in 2016 as
well, that’s undetermined where that’s going to be, right
now it is in the planning stages.

Slashdot:
Do you have to actually get together in person with anyone to take
part, or are there good opportunities if you can do it completely by
remote?

David:
I think you can definitely do it by remote. I know Python is a big
part of the community, and we see things on Twitter, just the other
day there was someone asking about they needed to create some new
documentation for some new aspects of Python and they were just
looking for writers to help out. So it could really be anybody. It
wouldn’t have to necessarily be in a particular city.

The only thing I would hate worse than documenting my code would be watching a video about documenting code.

If they video, which there is no chance I would watch, is about dictating documentation into a voice-recognition system then I'll apologize because I have no idea about if that is a good idea or not. But assuming that the documentation in question is normal written documentation that is written by writing then having a video about it sounds pretty stupid to me.

The enterprise linked in TFS is clearly for beginners. Beginners tend to be younger. Video is pretty much the preferred information delivery method (on the receiving end) for recent generations. The majority does not gravitate towards reading (and perhaps that accounts for why the writing problem is so prevalent as well.)

If you're working at a professional level, you can already prepare good documentation, and will, whenever it's called for. You may even have developed your own toolchain for doing so.

Right, people for whom video is the preferred delivery method are not going to write documentation. Or read it either. It is idiotic to make videos to connect with them to advocate to them that they read more. Their teachers already tried and failed, casual encouragement isn't going to move the needle.

If somebody cares enough about these unfortunates to try, they should just skip right ahead to videos teaching them to make video documentation for each other.

Sure, granted. But I'm not sure adding write-only interfaces would have any chance of outputting useful documentation. By "reading" I meant, becoming a person who participates in the exchange of knowledge via written words; e.g., a reader might then come across a missing section of documentation, and add to it. If you can't reach them with written words to discuss the issue then even if you talked them into writing they wouldn't be able to contribute. They have to be a reader in order to know which itch nee

While I consider myself to be a pretty darned good technical writer, now that my eyesight is going, I find I enjoy at least some information in the form of video or audio. Now GOOD video or audio has been scripted, and is thus FAR more difficult to create than written text alone. And writing for audio or video is a different skill from writing for reading, so there is yet another factor of difficulty.

On the other hand, if someone just turns on the camera and starts babbling, as do many of the supposedly med

1) I kind of expected to be routed to/dev/null when I click on the "Linux Doc" link.2) But, no, it's real site (http://www.tldp.org/)...whose unfriendly and unhelpful home page looks exactly like it was written and designed by a bunch of Linux coders.

The problem with the docs, or lack of, are those stupid requirements for them being in a specific mark-up language. Back in the day when you had to compile your own http + SSL, the docs were fucking awful. I fixed that; simple step by step instructions. However, my plain text was deemed "wrong format", and I had to go away and learn whatever shitty mark-up language was en-vogue at the time.

Rather than take the information and ask someone familiar with how they wanted it formatted, to bring it into line, the

I thought it was a good well meaning laugh. If you close your eyes, click this site, imagine a stereotype'd Linux help board based on a Bullentin Board UI design from the 90's....open your eyes and your there. Nothing bad to the folks doing good work there...but it is pretty funny. On purpose maybe?