Want to read Slashdot from your mobile device? Point it at m.slashdot.org and keep reading!


Forgot your password?

Video Write the Docs Helps Create FLOSS Software Documentation (Video) 27

Say hello to David Smatlak, who works with Write the Docs -- a group that started some years back as Read the Docs.They have conferences in the U.S.and Europe, and Meetups in over a dozen cities. It's a low-key group, open to both people who write documentation and developers who want help writing professeional-quality documentation for their Free/Libre/Open Source Software (FLOSS) projects. Also welcome are those who would like to learn how to write good software documentation, starting with this online tutorial about the art and science of writing technical documentation. (And if you are interested primarily in Linux documentation, you'll want to check the Linux Documentation Project, too.)

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.

This discussion has been archived. No new comments can be posted.

Write the Docs Helps Create FLOSS Software Documentation (Video)

Comments Filter:
  • Ugh..there is virtually NOTHING I hate more than having to write documentation, I avoid it at all costs.

    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!!

    • 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.

    • 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

      • 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

        • 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

          • by fyngyrz ( 762201 )

            It is idiotic to make videos to connect with them to advocate to them that they read more.

            I think the idea was to make video to encourage them to write more. Said encouragement is present. Compliance, well... :)

            • 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

        • 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

  • by xxxJonBoyxxx ( 565205 ) on Wednesday December 09, 2015 @05:55PM (#51091313)

    Why isn't the group named "WTFM"? ("Write the...")

  • by xxxJonBoyxxx ( 565205 ) on Wednesday December 09, 2015 @05:59PM (#51091345)

    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.

    • by Anonymous Coward

      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?
  • Write the Docs Helps Create FLOSS Software Documentation

    This, right here, is why title case for headlines is a stupid idea.

Order and simplification are the first steps toward mastery of a subject -- the actual enemy is the unknown. -- Thomas Mann