Ubuntu Wiki

Ubuntu Open Week - Documentation Team - Rich Johnson - Sat, Oct 27, 2007

19:06 -!- nixternal changed the topic of #ubuntu-classroom to: Ubuntu Open Week info: Information and Logs: https://wiki.ubuntu.com/UbuntuOpenWeek | Ubuntu classroom transcripts: https://wiki.ubuntu.com/ClassroomTranscripts | Please ask questions in #ubuntu-classroom-chat not here | Current session:  Ubuntu Documentation - Richard Johnson
19:08 <@nixternal> Hey everyone, welcome to Ubuntu OpenWeek - This talk will be about the Ubuntu Documentation Project
19:09 <@nixternal> I will start out with a short/brief introduction and talk about the project, and then plan on having an open forum at the end. I enjoy the open forum as it allows us to speak one-on-one allowing you to help control the pace
19:09 <@nixternal> So here we go!
19:09 <@nixternal> = Who am I? =
19:09 <@nixternal> My name is Richard Johnson. I am an Ubuntu member as well as a member of other teams within the Ubuntu community. I am known mostly around here as the Kubuntu and KDE documentation guy. So because of this, I will be talking to you all today about the Ubuntu Documentation Project. * '''Wiki Page''': ["RichardJohnson"] * '''LP Page''':   https://launchpad.net/~nixternal
19:10  * nixternal loves the great copy/paste effect there
19:10  * WanderingKnight too
19:10 <@nixternal> = What is the Ubuntu Documentation Project? =
19:10 <@nixternal> The project was created in order to create system documentation for the Ubuntu operating system. As time went on and Ubuntu matured, the scope of the project has widened. Currently the Ubuntu Documentation Project encompasses everything from the wikis to system documentation for each Ubuntu partner project (Kubuntu, Edubuntu, and Xubuntu).
19:11 <@nixternal> == Who is the Ubuntu Documentation Project? ==
19:11 <@nixternal> The project is comprised of the Ubuntu Documentation Team which is completely made up of volunteers. The core team is https://launchpad.net/~ubuntu-doc however many others contribute freely to the documentation all the time. The core team spends a majority of their time working on system documentation whereas the volunteers tend to start off adding documentation to the community wiki (https://help.ubuntu.com/community) an
19:11 <@nixternal> if that got cut off, please yell
19:11 < WanderingKnight> YELLING
19:11 < cjb_ie> "(https://help.ubuntu.com/community) an"
19:11 <@nixternal> gotcha, thanks
19:11 <@nixternal> and eventually work their way up to the core team.
19:12 <@nixternal> == What types of documentation does the team work on? ==
19:12 <@nixternal> There are essentially two types of documentation that the team produces.
19:12 <@nixternal> 1. System documentation - this is written in a markup language called DocBook/XML, and is hosted in the documentation repository.
19:12 <@nixternal> 2.  Online documentation - composed of an HTML version of #1, and a community driven wiki (https://help.ubuntu.com/community).
19:13 <@nixternal> == Why are there 2 wikis? ==
19:13 <@nixternal>  * https://wiki.ubuntu.com is looked at mainly as the developer wiki. This wiki is meant to store specifications and team information as well as personal wiki pages for members and future members.
19:13 <@nixternal>  * https://help.ubuntu.com/community is the community documentation wiki. Any and everyone is more than welcome to add their documentation to that wiki, or improve the documentation that is already there. This is the wiki to go for when you need help with your system.
19:14 <@nixternal> == How does one contribute to the project? ==
19:14 <@nixternal> Diving in and trying things out is the best way to begin getting involved. If you have edited a ton of wiki pages, or have experience with technical documentation, then maybe you should go ahead and download our repository (https://wiki.ubuntu.com/DocumentationTeam/Repository) and start getting familiar with DocBook/XML and the way we rock.
19:15 <@nixternal> NOTE:  We are currently in the process of creating the project on Launchpad with Bazaar as well - as that comes up to speed, we will announce how you can get involved with that as well.
19:15 <@nixternal> We have even included a validation tool in our repository to help you ensure the documentation you have created is logically valid. If you are confused or have any questions, please feel free to ask in #ubuntu-doc or on the mailing list (ubuntu-doc@lists.ubuntu.com). Be patient, as sometimes the IRC channel may be dead, however the mailing list is usually quick to provide a response.
19:16 <@nixternal> NOTE: Patience will be needed this week, as we are currently getting ready for the Ubuntu Developers Summit in Bostom, MA (USA)
19:16 <@nixternal> == What is this DocBook/XML you keep blabbing about? ==
19:16 <@nixternal> DocBook is a DTD (Document Type Definition) which includes a very popular set of tags for describing books, articles, and other prose documents. XML (eXtensible Markup Language) is a general purpose, free and open source, markup language. Both are fairly easy to pick up and learn. More information on DocBook is available at http://docbook.org/tdg/en/html/docbook.html.
19:18 <@nixternal> NOTE: If you can do HTML, you can easily do DocBook/XML. There are currently no WYSIWYG editors for DocBook/XML. Most people tend to use gEdit (Gnome), Kate (KDE), as well as a variety of web programming apps (Bluefish, Scream, Quanta+, and more)
19:18 <@nixternal> == I am not all up technically enough to document, what else can I do? ==
19:18 <@nixternal> Proof reading is a great way to get started as well. This will not only find our mistakes, but it will allow you to familiarize yourself with the ways that we do things. You can look through our documentation via the repository, or by visiting http://doc.ubuntu.com and reading through the documentation that gets built nightly via the repositories. Note this is a staging area and not a final release area.
19:18 <@nixternal> Also note the wiki section coming up!
19:19 <@nixternal> == What are the key tasks with the documentation team? ==
19:19 <@nixternal> There are actually quite a few tasks, and they continue to grow with each release. So due to this, we definitely have the need for more contributors. As it stands, these are just some of the key tasks:
19:19 <@nixternal>  * Improving the navigability and readability of the help (https://wiki.ubuntu.com/TopicBasedHelp)
19:19 <@nixternal>  * Incorporating material from the Official Ubuntu Book into appropriate sections in the system documentation, amending the style accordingly.
19:19 <@nixternal>  * Addressing areas which are missing from the documentation, in particular by reviewing material on the wiki/forum/mailing lists and converting it to DocBook for inclusion in the system documentation.
19:19 <@nixternal>  * Updating existing information which is no longer valid due to inclusion of new features in each release.
19:20 <@nixternal> == Wiki Documentation ==
19:20 <@nixternal> Contribution is as easy as logging into the wiki using your launchpad account, and then correct the errors you find in the documents. Read existing documents to become familiar with the wiki markup which is very easy to do. Some of you may have noticed = Question =, that is wiki markup which is similar to the <h1> or main header in HTML.
19:21 <@nixternal> The community documentation wiki also needs a little spring cleaning as well. So you can visit https://help.ubuntu.com/community/CategoryCleanup and go through and proof the pages, and make them conform to the Wiki Guide at https://help.ubuntu.com/community/WikiGuide. After you have edited and cleaned up a few pages, apply to join the Wiki Team at https://beta.launchpad.net/~ubuntu-wiki.
19:21 <@nixternal> Or depending on where you are in the world, Summer, Fall, or Winter cleanup :)
19:21 <@nixternal> == Is there any one task you really need help with on the wiki? ==
19:21 <@nixternal> Cleaning out the CategoryCleanup category on the wiki is a big task for wiki pages at this time. You can see which documentation is in need of some cleaning. Refer to the previous topic under Wiki Documentation.
19:22 <@nixternal> == Like system documentation are there key tasks for the wiki? ==
19:22 <@nixternal> Sure there are. Here are just a few of them now:
19:22 <@nixternal>  * Improve the self-maintainability of the wiki by introducing easy tools for quality assurance (https://wiki.ubuntu.com/HelpWikiQualityAssurance). This spec needs ideas, discussion and eventually some code.
19:22 <@nixternal>  * Doing quality assurance to ensure users are given reliable information and can quickly identify how reliable a page is.
19:22 <@nixternal>  * Improving existing material and adding new material to the wiki, in particular drawing on the immense resources offered by the forums (https://help.ubuntu.com/community/forum).
19:23 <@nixternal>  
19:23 <@nixternal> A main goal is to bring the system documentation and the online documentation closer and closer together, so eventually it is easy for the system documentation to draw on contributions via the wiki, and users to browse and search all of the available documentation via a single interface, be it via the online website or the system help viewer. This is a very large goal awaiting the right tools to come together.
19:23 <@nixternal>  
19:23 <@nixternal> == TRANSLATIONS!!! ==
19:23 <@nixternal> No question really, but I don't know if you all realize this or not, but translators are one of the largest assets of the Ubuntu community. Ubuntu is known as an operating system with more translations than any other. We can never have enough truthfully, so if you are a translator and are interested in helping out, then you just need to learn the Rosetta translation system (https://launchpad.net/rosetta).
19:24 <@nixternal>  
19:24 <@nixternal> You can find out how to use that on the Rosetta wiki page (https://wiki.ubuntu.com/Rosetta). Once you have brushed up on all of this, the docteam documents can be found at https://launchpad.net/distros/ubuntu/hardy/+source/ubuntu-docs. Replace ubuntu-docs with kubuntu-docs, xubuntu-docs, and/or edubuntu-docs accordingly.
19:24 <@nixternal>  
19:24 <@nixternal> == Conclusion ==
19:24 <@nixternal> Thank you for staying awake during this little speech. I hope I was able to provide you with viable information to help you get started. If you come up with any questions, any problems, or whatever, please feel free to contact me anytime (nixternal@ubuntu.com). To contact the team try any of the following:
19:24 <@nixternal>  * IRC - server: chat.freenode.net - port: 8001 - channel: #ubuntu-doc
19:25 <@nixternal>  * Mailing List - ubuntu-doc@lists.ubuntu.com - subscribe or read the archives at https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc.
19:25 <@nixternal>  * Wiki - https://wiki.ubuntu.com/DocumentationTeam
19:25 <@nixternal>  
19:26 <@nixternal> At this point I would generally ask for questions in the chat channel, but I think having you ask them directly, keeping it fun and upbeat, provides the best results....so let them fly...just take it easy, I haven't had lunch yet and my eyes are a little crossed :)
19:26 <@nixternal> if there are Questions, can someone please copy/paste them into here so they can be addressed first?
19:26 -!- mode/#ubuntu-classroom [+v posingaspopular] by nixternal
19:26 <@nixternal> you seem like the perfect candidate
19:27 <@nixternal> zzZZzZzZZZzzZzzzZZZzZzz :p
19:28 <@nixternal> alrighty then, no questions...I can see everyone stayed awake for this one
19:29 < ttread> QUESTION: Installation is one of the first problems new users face, but it's not covered in the official doc.  In the community doc, the graphical install section was written for Dapper.  Why?
19:29 <@nixternal> there we go
19:30 <@nixternal> ttread: It seems nobody has updated that page. Usually the community members take care of it, but as you can see, it has slide a little bit. The reason it isn't covered in the official documentation is because it is now meant to be used once the system is installed
19:31 <@nixternal> this occurred when we switched away from the Ubuntu Desktop Guide to the Topic Based Help
19:31 <@nixternal> There is an installation guide somewhere in the repositories that would be great to have updated for the future as well
19:32 <@nixternal> definitely something that needs to be added to our TODO list though
19:33 <@nixternal> jussi01: that would be great, since my nemesis seems to be elsewhere :)
19:33 <@nixternal> this would be the 2nd talk where the mouse is currently sitting in its cradle taking a charge :)
19:33 <+jussi01>  <posingaspopular> QUESTION: which parts of the Ubuntu Documentation need the most work, for new users to get a good start?
19:33 <+jussi01> nixternal: please say next when you are done :)
19:34 <@nixternal> posingaspopular: as you can see from ttread's question, the Community Wiki is a great place to start
19:34 <@nixternal> posingaspopular: the most work is definitely needed with the system documentation as well though
19:34 <@nixternal> The Kubuntu, Edubuntu, and Xubuntu documentation really needs more eyes. And if you use any of those then I would recommend hopping on with one of them
19:34 <@nixternal> next...
19:35 -!- mode/#ubuntu-classroom [-v posingaspopular] by nixternal
19:35 <+jussi01> <desertc> QUESTION: When will the documentation get updated to 7.10, in so much as what is the process for that to occur?
19:35 <@nixternal> 7.10 has been updated and released with the install. Not sure if I follow that questions 100%. desertc feel free to elaborate more in here.
19:36 < desertc> Is this page part of the documentation project?
19:36 < desertc> https://help.ubuntu.com/
19:36 <@nixternal> ahh, yes it is
19:37 <@nixternal> that is actually to be updated by the Canonical Systems Admin who has access to that page. Unfortunately the community doesn't have access to that one :(
19:37 <@nixternal> I will poke Matt and tell him to hurry up, the masses are chomping at the bit :)
19:38 <@nixternal> next...
19:38 <+jussi01> <nikolam> QUESTION: What is status of Documentation localizations?
19:38 <@nixternal> that was quick
19:38 <+jussi01> nixternal: I'm on the ball ;)
19:39 <@nixternal> I really don't know the status. As for translations, all of the ones that were complete for release are available. As for localizing them on the web, that is up to the local community teams I believe
19:39 <@nixternal> nikolam: I think the best answer for that question can probably be grabbed from Matthew East (mdke on IRC in #ubuntu-doc)
19:39 <@nixternal> you can also try our mailing list to find out more
19:39 <@nixternal> next...
19:40 <@nixternal> thought you were on that ball? or are we flat out of questions?
19:40 <+jussi01>  <spd106> QUESTION: When is it ok to delete old and abandoned wiki pages?
19:40 <@nixternal> :p
19:40 <+jussi01> crap I have some lag
19:40 <@nixternal> ooh, got me
19:40 <@nixternal> hehe
19:41 < nikolam> thanks
19:41 <@nixternal> spd106: never. Either we need to get those pages updated, or if they don't need to be updated, at least preserve them just in case someone needs to use it
19:41 <+jussi01> if i disapper, please someone take over... :(
19:41 <@nixternal> next...
19:41 <+jussi01> [22:28] <BonesolTeraDyne> QUESTION: How many people are working on the docs as their main task?
19:41 <@nixternal> jussi01: if you disappear, I will just open it up to the world..which I plan on doing for suggestions and ideas
19:42 < rohan> i can take over, jussi01
19:42 <@nixternal> BonesolTeraDyne: there is really only a small handful that does it as their main task
19:42 <+jussi01> rohan: thanks. I going to go sort out my connection
19:42 <@nixternal> I do a lot only because I enjoy it, which has really turned into a main task for me, but I do a lot of development type work as well
19:43 < rohan> jussi01: ok, just tell me when you're ready to hand over the baton to me :)
19:43 < popey> i am not here
19:43 <@nixternal> I think every project has 2 main documenters... 2 for Ubuntu, 2 for Kubuntu, 2 for Xubuntu, and 2 for Edubuntu
19:43 <@nixternal> and we didn't plan for it like that, it is just slow in the doc world, and you can see we definitely need the added eyes
19:44 <@nixternal> next...
19:44 <+jussi01> <nikolam> QUESTION: What is a minimum of localizations that needs to be done, so that we can say we have localized U/K/Xubunutu? Does All types of Ubuntu must be localized on the same moment?
19:44 < rohan> 01:03 < nikolam> QUESTION: What is a minimum of localizations that needs to be done, so that we can say we have localized U/K/Xubunutu? Does All types of Ubuntu must be localized on the same moment?
19:44 <@nixternal> there we go
19:45 <@nixternal> nikolam: Yes :) I don't know if we have a minimum really, we can only use what has been done, and we can't expect all of them to be done as 99.9% of the people are volunteers, and some, unlike me, have a life outside of Linux :)
19:45 <@nixternal> We have a cut off, which is about a month or so prior to the final release that we allow the translators to catch up
19:45 <@nixternal> but that doesn't mean they don't start translating from day one
19:46 <@nixternal> we try to upload updates throughout the development cycle so that they have something to work with
19:46 <@nixternal> the bigger countries with more users of course seem to fly through translations
19:46 <@nixternal> next...
19:46 < rohan> that's it for now, nixternal
19:46 <@nixternal> OK, that seems it...so open it up and let everyone speak their mind! :)
19:47 <@nixternal> do you all have any ideas? suggestions? complaints?
19:47 <@nixternal> come on in here and join me :)
19:47 <@nixternal> I won't bite, but I don't know about rohan
19:47 < rohan> nixternal: one question, because i missed the starting of the session - what's the way i jump in and start helping with docs ?
19:47 < rohan> editing wiki pages ?
19:48 <@nixternal> you answered your own question...just jump in where you feel the most comfortable really...jumping in is what it is all about...
19:48 <@nixternal> wiki pages are good so you can get your flow going
19:48 < rohan> hehe, i don't bite .. not right now, because the moon is hidden by the clouds ;)
19:48 <@nixternal> but don't forget to check out the repository and go through the code to get an understanding
19:48 < sommer> nixternal: I'm not sure if this has been asked, but do the official docs get some of their content from the Wiki?
19:48 <@nixternal> aaaaawhooooooo <- rohan howling at the moon
19:49 < posingaspopular> nixternal: thanks.
19:49 <@nixternal> sommer: yes...we have recently changed the licensing on the Wiki and the System Documentation so we can do just that
19:49 <@nixternal> CC-by-SA (3.0 I believe now)
19:50 < sommer> cool, thanks.
19:50 <@nixternal> no problem
19:50 <@nixternal> how many miss the Desktop Guide if they were around for it?
19:50 < BonesolTeraDyne> nixternal: What app do you suggest for new doc writers to use when making something in docbook format?
19:50 < rohan> nixternal: just for the record, can you give us a brief runup of the license ? if i edit a wiki page, who owns "my" text ? ubuntu ? community ? me ? what about official documentation ?
19:50 < BonesolTeraDyne> nixternal: I miss it
19:51 <@nixternal> BonesolTeraDyne: what is your favorite text editor? a majority of them have a plugin just for DocBook
19:51 <@nixternal> gEdit is great if you use Gnome, Kate is amazing if you use KDE, VI has their own, as well as Emacs
19:51 < BonesolTeraDyne> nixternal: in GUI, it's kate, and in term, it's VIM
19:51 <@nixternal> Kate allows you to validate as well, there is a plugin for it
19:52 < posingaspopular> geany
19:52 <@nixternal> kate-plugins
19:52 < BonesolTeraDyne> ok. thanks
19:52 <@nixternal> ya, you can use Geany, Bluefish, Scream, Quanta, and I am sure Kompozer which is the new Nvu as well
19:53 <@nixternal> rohan: researching your question really quick..I want to be positive on my answer
19:53 < BonesolTeraDyne> I might try Quanta, since I already use it for working on my website.
19:54 <@nixternal> https://help.ubuntu.com/community/License
19:54 <@nixternal> that doesn't answer it 100% either
19:54 <@nixternal> rohan:  "Contributors to the Ubuntu documentation wiki"
19:55 < rohan> aha, thanks nixternal
19:55 <@nixternal> so they don't license it individually
19:55  * nixternal grumbles at that, but it isn't up to me unfortunately
19:55  * nixternal is a GPL fan anyways :
19:56 <@nixternal> any ideas on how we can fix things? anything we might add? can we make stuff easier/better?
19:58 < sommer> I notice the community wiki is a couple MoinMoin versions behind... :)
19:59 <@nixternal> yes it is...and what a pity
19:59 <@nixternal> now for the reason...
20:00 <@nixternal> our version of MoinMoin is so modified, it would take a small army to do all of the core updates...which is definitely planned, but for when I couldn't tell you precisely
20:00 <@nixternal> Ubuntu and MoinMoin share a strong bond/partnership, so I know/hope it can only get better
20:01 < sommer> ah... that's what I was thinking.
20:02 <@nixternal> hopefully it will get updated soon, but I have heard "rumors" of MediaWiki...but as I said so far they have been vapor/rumors
20:03 < cpu> anybody from Montenegro/Serbia/Croatia?
20:03 < sommer> cool thanks nixternal.
20:03 <@nixternal> no problem, thanks for the questions
20:03 <@nixternal> and I think there is one more talk left