On Mon, 2010-06-28 at 18:24 -0400, Tiffany Antopolski wrote: > Hi, > > I am a fourth year software engineering student, and I am very > interested in getting involved in GDP. I would like to write new > documentation for applications in need of new or updated user docs (I > think this would be a good place to start). However, I don't really > know how to go about getting involved. > > I was just reading through the Documentation Project pages on > live.gnome.org. How would I actually start participating in > contributing to the project if I was interested in writing user docs for > one of the apps listed there (for example Evince). Who would I contact? > > At the moment I do not have any experience with open-source (except for > being a ubuntu user). Any guidance, advice, help, or being pointed in > the right direction would be greatly appreciated. > > I am 'mimico' on irc. Hope to see you there. > > Thanks and cheers, > > Tiffany Antopolski
Hi Tiffany, Thanks for introducing yourself via email and wanting to help out with GNOME documentation. I apparently have a new project for the weekend, as our Contributing page on the wiki is out of date.[1] If you're interested in writing docs, a few things to check out: 1. Review the GNOME Documentation Style Guide. [2] While some pieces of it are out of date, the sections on grammar, international audiences, GUIs, usability and accessbility are really good. 2. Set up your environment using Git [3] You'll want to learn some Git basics - the easiest way after writing new or updated docs for an application is to submit a patch using git. The wiki page above has everything you'll need to set up git and how to create a patch when you're ready. (Depending on the Linux distribution you use, you may have to install git). 3. Pick a project You can start by either fixing little things filed as bugs in gnome-user-docs in GNOME Bugzilla[4] or start writing new help for an existing application (you mentioned Evince above). Either way, you'll want to do a git checkout of the application you're going to work on and submit a patch with your changes in GNOME Bugzilla. 4. Pick a language If you're working on updating existing documentation, chances are it was written in Docbook. If you're working on new documentation, we recommend Mallard. We are transitioning to topic based help - small chunks of help that focus on one thing and help the user get the help they need faster. The Mallard language was created specifically for topic based help - not only does it have an easier syntax to learn than Docbook, it will help in creating topic based help and linking to other topics. Now is a great time to join the Docs team as we're just starting this process - last fall Empathy's help was written in Mallard and this past March in GNOME 2.30 more applications adopted it, including Brasero, Cheese, and a couple more I'm forgetting. Tomboy's new Mallard help was integrated just today and Rhythmbox and Bansee are under active development too. Which means that almost any GNOME application could use new help written in Mallard, so we're going to be busy. :) One other change is we're using a new license for help (Creative Commons CC-BY 3.0 instead of the GFDL) which means in almost all cases we have to write new help from scratch. (Which is fine as topic based help is organized differently). 5. Plan your writing The hardest part in writing documentation is thinking about what you're going to write about. Since we're doing topic based help, you will need to brainstorm all of the topics you think should be included in the help, and then brainstorm some more. I recommend making the process as collaborative as possible - email the Docs list with your topic ideas, use the Docs wiki where you can see some brainstorming examples[5], and also reach out to the application's developers with the list too. Join the app's mailing list and follow along of what is actively in development. 6. Write, Write, Write And edit, edit, edit. 7. Get reviews As you progress, get peer reviews. Ask in #docs in IRC or on the mailing list - we're here to help and like to think we have an open and welcoming community. (Though IRC you might have to wait a bit sometimes). Before help is considered final, we ask for a peer review from the docs team and a review from the application's developer team. 8. Have fun! This may sound like a lot of stuff - but once you get set up a lot of it will come to you, and practice makes perfect. Most of us hang out in IRC so you can usually get fairly quick answers (assuming you're on Europe or US time). Thanks again for the email and let us know if you have any questions. (And if I've missed anything, Shaun, Phil or Milo can add more!) Paul [1] http://live.gnome.org/DocumentationProject/Contributing [2] http://library.gnome.org/devel/gdp-style-guide/stable/ [3] http://live.gnome.org/Git/Developers [4] https://bugzilla.gnome.org/browse.cgi?product=gnome-user-docs [5] http://live.gnome.org/DocumentationProject/Planning _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
