Slashdot Mirror

← Back to Stories (view on slashdot.org)

Write the Docs Helps Create FLOSS Software Documentation (Video)

Posted by Roblimo on from the a-million-monkeys-with-a-million-monkey-can-create-all-the-docs-we-need dept.

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

27 comments

  1. Documentation is a 4-Letter word!! by cayenne8 · · Score: 1
    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!!

    --
    Light travels faster than sound. This is why some people appear bright until you hear them speak.........
    1. Re:Documentation is a 4-Letter word!! by sunderland56 · · Score: 1

      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.

    2. Re:Documentation is a 4-Letter word!! by Aighearach · · Score: 1

      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 documentation so badly, maybe they could find a volunteer that would make a transcript, then when people are writing documentation they can use the information asynchronously.

  2. Why isn't the group named "WTFM"? by xxxJonBoyxxx · · Score: 4, Funny

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

    1. Re:Why isn't the group named "WTFM"? by fyngyrz · · Score: 1

      I don't know, but I just renamed my custom documentation system to "wtfm", because genius. :)

      --
      I've fallen off your lawn, and I can't get up.
    2. Re:Why isn't the group named "WTFM"? by fyngyrz · · Score: 1

      Also, FYI, I just credited you for it, too.

      --
      I've fallen off your lawn, and I can't get up.
  3. About The Linux Doc Page by xxxJonBoyxxx · · Score: 3, 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.

    1. Re:About The Linux Doc Page by Anonymous Coward · · Score: 0

      They're a group of technical writers, not webdesigners. Still, I'm sure they'd accept improvements to their page if you submit them to their mailing list.

    2. Re:About The Linux Doc Page by xxxJonBoyxxx · · Score: 1

      >> 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. :)

    3. Re:About The Linux Doc Page by Anonymous Coward · · 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, they would rather we all "fuck off". Then you have the domain campers, those that wrote docs, got them accepted because they used wanky-tags, but they were incorrect, missing information or ridiculously out of date. Any attempts to send changes were "fuck off" in true wiki tradition, long before Jones and his merry gang started doing it.

      I spoke to a number of others at college and in work later regarding linux and how shit docs are compared to other OSes, especially when o'rielly didn't have a book on the subject, same conclusion. Those that were gatekeepers were more concerned with fucking shitty mark-up and tool-sets rather than the actual information.

      Now distros have dumbed it all down, there's probably no need for tldp; unlike two decades ago.

    4. Re:About The Linux Doc Page by sasparillascott · · Score: 1

      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?

  4. NO TOR ANY MORE ! by Anonymous Coward · · Score: 0

    SD cannot be reached via TOR any more. Well, FUCK YOU, then.

    Time to build a Distributed, Decentralized Slashdot.

    1. Re:NO TOR ANY MORE ! by Anonymous Coward · · Score: 0

      Just press the "New Tor circuit for this Site" button, and if that doesn't work, press the "New Identity button", until you get a non-banned IP.

      It happens that some IPs get blacklisted from SD because of reasons.

      I know this because I use TOR for enhancing my trolling capabilities (in fact this post is written through TOR). Any non-childish slashdot trolling is prevented by the IP filter you know all the "depending on moderation" bla bla. I am like japan. Running an experiment, about how much trolling slashdot can endure via TOR so that its still kept. And the only way to find the border is, as explained by thoughtful readers in the japan whale fishing article, by crossing it.

      So if you ever see TOR banned from slashdot for real, don't blame DICE or cowboyneal. Blame the trolls that work day and night in the name of science.

  5. Write the docs uses the integrated face system by Anonymous Coward · · Score: 0

    Write the docs uses the integrated face system to write documentation.

  6. What? by wonkey_monkey · · Score: 1

    Write the Docs Helps Create FLOSS Software Documentation

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

    --
    systemd is Roko's Basilisk.
  7. Working It It by Anonymous Coward · · Score: 0

    I've got the hurd docs nearly done but I'm not quite there yet.

    1. Re:Working It It by Aighearach · · Score: 1

      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.

  8. professeional? by Anonymous Coward · · Score: 0

    Hopefully they spell check their docs...

  9. Good docs distinguish the pros from the herd by fyngyrz · · Score: 2

    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 can't prepare good documentation when it is needed, or won't, but think you're working at a professional level... you're wrong. :)

    --
    I've fallen off your lawn, and I can't get up.
    1. Re:Good docs distinguish the pros from the herd by Aighearach · · Score: 2

      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 the late 90s, and the vast majority of that software has extensive documentation. That was true then, and it remains true now. Though I can also say from experience that if you're using recently-popular programming frameworks, the documentation won't be finished until after the fad passes, leaving most of the people who briefly used it during the heyday with the idea that it is poorly documented, even where the people using it successfully have high quality documentation. In many cases, the documentation was always there, but individual blogs describing techniques get more links. Often this is compounded by a culture of experimentation that inadvertently discourages reading manuals; you can spot this by all the people that run to a paste site to ask questions that would have been answered by a small subset of the same words being entered into a search bar.

    2. Re:Good docs distinguish the pros from the herd by fyngyrz · · Score: 1

      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've fallen off your lawn, and I can't get up.
    3. Re:Good docs distinguish the pros from the herd by Aighearach · · Score: 1

      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 needs scratching.

    4. Re: Good docs distinguish the pros from the herd by GrantRobertson · · Score: 1

      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 media-literate generation, then I won't watch it because it is a waste of my time.

    5. Re:Good docs distinguish the pros from the herd by Anonymous Coward · · Score: 0

      Video is pretty much the preferred information delivery method (on the receiving end) for recent generations.

      Not when it's a video of some fat tub of lard with man-boobs.

  10. ... who want help writing professeional-quality ,, by Anonymous Coward · · Score: 0

    That's a good one.

  11. If he wrote Smalltalk manual... by Anonymous Coward · · Score: 0

    If David Smatlak wrote a Smalltalk manual, then he could call it Smatlack on Smalltalk.

  12. Hard to get started at all! by Anonymous Coward · · Score: 0

    I tried looking for doc that needed written. Very, very, very hard. Each project has its own thing as far as doc formats, web site, etc. I had trouble figuring out what any given project needed or what to do to start. Some kind of central clearinghouse would be nice, but not sure how anyone would pull it off.