Video Write the Docs Helps Create FLOSS Software Documentation (Video) 27
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.
Documentation is a 4-Letter word!! (Score:2)
About the only thing I hate more than writing documentation, is mowing the fscking lawn....ugh.
I'd much rather pay other people to do both!!
Re: (Score:2)
Ugh..there is virtually NOTHING I hate more than having to write documentation, I avoid it at all costs.
Kind of like flossing?
Seriously - if you want someone to like something and help out, FLOSS might be a bad name.
Re: (Score:2)
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.
If people didn't hate writing documentati
Good docs distinguish the pros from the herd (Score:3)
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.
If you
Re: (Score:3)
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.
As an aside, I've been way over 99% FLOSS since th
Re: (Score:2)
I think the idea was to make video to encourage them to write more. Said encouragement is present. Compliance, well... :)
Re: (Score:2)
I think the idea was to make video to encourage them to write more.
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
Re: Good docs distinguish the pros from the herd (Score:2)
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
Why isn't the group named "WTFM"? (Score:5, Funny)
Why isn't the group named "WTFM"? ("Write the...")
Re: (Score:2)
I don't know, but I just renamed my custom documentation system to "wtfm", because genius. :)
Re: (Score:2)
Also, FYI, I just credited you for it, too.
About The Linux Doc Page (Score:4, Interesting)
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.
Re: (Score:2)
>> I'm sure they'd accept improvements...if you submit them to their mailing list.
For once I can't tell if I'm being trolled. :)
Re: (Score:1)
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
Re: (Score:2)
What? (Score:2)
Write the Docs Helps Create FLOSS Software Documentation
This, right here, is why title case for headlines is a stupid idea.
Re: (Score:2)
I've got the hurd docs nearly done but I'm not quite there yet.
Okay, but you've only got 5 years left until my decadal query, "is the Hurd here yet?"
Hurry up, 5 years goes fast in the age brackets of probable Hurd users.