[FM Discuss] Introduction, and request for help

[M R]

Hi Jacob, and also Debbie.


I came to this list with a pretty much identical request about 6 months ago.   The guy who basically owns this list and can set you up with permissions -- and who will doubtless answer this later (he's based in UK)--is Mick Chesterman.   But I can share my own experience, which has been extremely productive.


The premise of Floss manuals, as I'm sure you've seen, is open-source documentation for open-source software.  Like you, I actually expected to start just by helping to edit or proofread someone else's manual-in-progress (I have a literature-academic background though also a fair amount of tech experience).   However, Mick suggested I should look over the existing Floss books, get a sense of the range of software (and software-uses) they covered, and see if I might have the domain knowledge to either rewrite/update/extend an existing book, or else write a totally new one.   As it turns out I ended up doing both.


First, I noticed that they had a manual on Audacity, probably the world's leading open-source sound editor.  I've had substantial experience with Audacity.  It was a good intro manual but also years out of date, so I volunteered to update it to the latest Audacity release.  I kept nearly all of the original book's UI exploration and how-to chapters structure, but much of that had to be rewritten as the UI/features had changed so much, and of course it needed new screenshots throughout.  This was my first ever experience with working on an end-user manual and it was a perfect way to start.  I am a Windows-only person so I needed others to fill in the Mac OS and Linux OS installation pieces, and I easily found volunteers on the list willing to do that.  You could do the same whatever your own 'home' OS is.


With that being completed successfully (Mick and some others had a look and approved, and the new version was published officially to the Floss platform), I then considered writing (or at least starting) a totally new manual.  I've done some video editing as well, and had become aware of a great open-source editor called Shotcut which, being developed by a very small team, had extremely sparse 'official' documentation -- like a handful of brief how-to videos but almost zero textual documentation.   So I studied the Floss manual for a different open-source video editor, decided what I would and wouldn't follow in their approach, learned Shotcut a lot better than I had up to that point, and just...wrote it.  I did the UI/workflow overview and a bunch of basic how-to chapters, leaving another (promised) section on "advanced" operations for other, later contributors who knew either Shotcut specifically or video editing generally more thoroughly than I did (if some was familiar with, say, color enhancement in some other vid-ed software, presumably they could figure out how Shotcut specifically did that, as it's pretty full-featured).   Again I got Mac and Linux users to do their install pieces, but the rest, including extensive screenshots, was all done on my little Windows laptop.  A few folks reviewed, and again the manual was published.


I detail these just as paradigms to consider following if you want to quickly ramp up your end-user manual experience, and incidentally get some work samples 😊.  Obviously they involve having some kind of software competence and confidence, but we all use some kind of software, and I've found that nearly every genre of commercial software now has open-source analogs.  I'd also note that it doesn't matter whether the open--source software is already documented or not, as long as it's not documented on Floss and esp if there's any room you can see for better/different documentation.  As I said, Shotcut had virtually no written documentation, at all, so that was easy.  Audacity had extensive (and up to date) official written documentation but more in a help-wiki form than a single manual.


I bet there's actually a Floss manual already on how to start writing Floss manuals, with what I've written above; I haven't checked.  There's definitely one on how to use the Floss BookType framework/software itself, though as that platform's just been very significantly upgraded, I'm not sure the manual is up to date.  Mick would know.  Hey, that's an idea....


best,


Matt Roberts



________________________________
From: Discuss <discuss-bounces at lists.flossmanuals.net> on behalf of Jake G. <jacob.benj.greene at gmail.com>
Sent: Friday, May 4, 2018 1:27 PM
To: discuss at lists.flossmanuals.net
Subject: [FM Discuss] Introduction, and request for help

Hello,

My name is Jacob, and I've recently joined the mailing list and FLOSS Manuals. I'm new to writing and editing manuals, but I'm looking to develop these skills and gain experience. I'm not entirely sure if this is the right place to ask, but I thought I might as well include it with my introduction.

If any of you are looking for a volunteer, I'd love to join you on your projects to help out with editing or fact checking. I hope to write manuals of my own eventually, but I'd appreciate any opportunity to join you and learn firsthand. Hope you all are having a great day!

Best,
Jacob
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20180504/987bf4df/attachment.html>