[01:38] starcraft-ntbk: :-) nice name [01:38] you play sc? [01:40] skiquel: Hello [01:40] new doc member? [01:41] skiquel: as for SC, not so much anymore. I'm too busy for ga. [01:52] starcraft-ntbk: I don't know if I'm a "member" yet, but I'm trying to contribute :) [01:54] skiquel: ah ha, well I been here a while, need some help? [01:57] skiquel: people some times have trouble finding info and documentation on getting started, you know where to get info on markup and system documenttion? The Doc team home yes? [02:04] starcraft-ntbk: I've seen the page yeah :-) just being prudent, i don't want to make a new page on something like xmonad or weechat and get it deleted first thing [02:10] skiquel: try first time round then editting see the tags section. Don't need to make new pages. [08:24] wah? === That_Wiki_Guy is now known as ZachK_ === ZachK_ is now known as Guest30131 === Memememe is now known as ZachK_ === ZachK_ is now known as Guest15240 === That_Wiki_Guy is now known as ZachK_ [16:57] Hey everyone! I'm going to be giving a talk in a few minutes on the Documentation process. [16:58] Phil Bull will follow with info on Mallard! [16:58] missaugustina: yay! I thought I'd seen a mention last week and then it hadn't been mentioned since so I wasn't sure if it was actually happening :) [17:00] Alright it's 1700 UTC, I believe [17:00] Here in the USA West Coast Pacific Time it's 9am, so if my time conversion is correct it's time to get started! [17:01] It is :) [17:01] Excellent. [17:01] I will present my information and take q&a at the end. [17:01] Please hold all questions until that time. Or, feel free to msg me directly and I'll get to your question when I'm done. [17:01] The purpose of this session is to review the steps contributors should take when preparing documentation. [17:02] By taking preliminary steps to plan and structure documentation before any writing begins, the documentation will be more effective, better organized, and ultimately, more useful. [17:02] This session will follow this agenda: [17:02] 1. Overview [17:02] 2. Define the Goal of the Document [17:02] 3. Define Use Cases [17:02] 4. Define the Audience [17:03] 5. Research Common Issues and Questions [17:03] 6. Propose an Outline [17:03] 7. Submit to Doc Team [17:03] 8. 8. When to Begin Writing [17:03] ==Overview== [17:03] The reason I proposed this session is that many new contributors seem to face similar challenges when preparing new documentation. [17:04] I also felt it might be helpful for veteran documentation team members looking to improve their writing. [17:04] This preparation process is not only important to focus your writing, but also clarifies your task to the rest of the team. [17:04] For instance, if you are writing documentation for novice users of an application, providing that information up front will ensure you get relevant questions and feedback. [17:04] Not communicating the scope of your documentation up front may produce feedback that isn't relevant to your task and can create a frustrating experience for the team. [17:04] Remember that when you contribute to Ubuntu Documentation, you're not working in isolation. You are part of a team! [17:05] The methods discussed in this session do not need to be performed in any particular order. You can use one or two of these methods, or all of them if you like. Ultimately it depends on what is useful for your documentation. [17:05] If something is helpful, then use it. If it's tedious, confusing, and doesn't add anything to the quality of your documentation, then don't use it. [17:05] ==Define the Goal of the Document== [17:05] Prior to writing any documentation, you should think about who you are writing the document for and what purpose it serves. [17:06] Software Engineering and Usability both provide processes that we can borrow from for writing documentation. [17:06] Software Engineering defines an Objective during the planning phase of an application. Engineers need to clearly understand the purpose of what they are developing. [17:06] In Documentation, we can also define an Objective or Goal for our document. [17:07] Defining a goal gives you a reference point when writing your documentation. [17:07] When considering whether to include something or when determining how to word or structure something, ask yourself how it fits with the goal you've defined for your documentation. [17:07] Defining a goal also clarifies the scope and direction of your documentation for the rest of the team. [17:07] For example, the goal of documentation for the Make A USB Startup Disk application is: "Instruct a novice user to make a bootable USB drive (LiveUSB)." [17:07] The goal of documentation for the Ubuntu Packaging Guide is "Provide a comprehensive reference of packaging tools and methods for novice users, expert users, and developers" [17:08] Your goal should be very general and describe the scope of your documentation in terms of the bigger picture. [17:08] ==Define Use Cases== [17:08] In Software Engineering, prior to developing an application, developers define use cases to outline the different functions their application will serve. [17:08] A use case is a task for which someone will use the software. [17:09] To define a list of use cases, ask yourself, what will someone want to do with this software? [17:09] You can create a list of use cases by playing around with the application, working with the developer or development team, or by reviewing existing documentation. [17:09] Use cases can be as simple as "Edit database record" or as complex as "Authenticate login details". [17:09] The wording isn't as important as identifying the task. [17:10] You can get as granular as you like when defining use cases. Make sure the use cases you define are in line with the goal you've specified. [17:10] ==Define the Audience== [17:10] Usability Experts typically define generic user profiles to clarify what types of people will be using a software application. [17:10] A persona is a fictional profile meant to represent a typical set of users for the application. [17:11] This profile can be as detailed or as general as you like. [17:11] The point of a persona is to clarify your user audience and to provide a tool for you to put yourself in your readers' shoes. [17:11] By understanding the circumstances under which your reader will be accessing your documentation, you can provide more effective documentation that provides an overall positive experience for the end-user. [17:12] Think about how many times you've used documentation and felt frustrated because you couldn't find the answer to your question! [17:12] When preparing to write documentation, think about who will be using the application you are documenting. [17:12] What is their general computer skill level? Novice? Intermediate? Advanced? [17:12] What is their experience level with Ubuntu? Novice? Intermediate? Advanced? [17:13] Note that a user can be an advanced computer user but a novice to Ubuntu. Documentation for specialized networking applications might target this audience. [17:13] Typically you want to cater your documentation to the lowest skill level you've defined for your audience. [17:13] You can create special sections on specific topics for advanced users. [17:13] Think about why someone would be using this application. User forums are great for getting this information. [17:13] What kind of application is this? [17:14] Is it a general desktop application or is it a specialized application for developers? [17:14] These are just some questions to get you started when you begin thinking about your audience. [17:14] Here is an example of personas I defined for the Ubuntu Packaging Guide. [17:15] https://wiki.ubuntu.com/AugustinaBlair/PackagingGuidePersonas [17:15] You can find more information about Personas on Usability.gov, a website focused on usability run by the U.S. Government. [17:15] http://www.usability.gov/methods/analyze_current/personas.html [17:15] Note that you don't have to have both use cases and personas defined for every document you write. [17:15] Some documents are general enough that focusing on tasks only is more appropriate. [17:15] An example of this is the Make USB Startup disk documentation. [17:16] It makes more sense for a document like this to focus on Use Cases and less on user profiles. The application is straightforward and regardless of the end-user's level of expertise, they will use the same information to perform the same tasks. [17:16] Other documents should cater more towards the types of users, especially if the tasks are widely varied. [17:16] An example of this is the Ubuntu Packaging Guide. [17:16] This is a very complicated document that covers a lot of different tasks. [17:17] It makes more sense to define Personas and then define document sections to target those personas and what information they will need to perform typical tasks for their user profile. [17:17] ==Research Common Issues and Questions== [17:18] Use the Ubuntu Forums to find out where current users have questions! [17:18] http://www.ubuntuforums.org [17:18] The forums are a great place to survey the landscape of what documentation is needed before writing a single word. [17:18] Here are some questions to get you started: [17:18] 1. What are people using the application for? [17:19] 2. Where are people experiencing the most confusion when using the application? [17:19] 3. What are the most common questions about the application? [17:19] 4. What are the skill levels (as far as you can tell) of the most vocal users? [17:19] 5. What information would answer most of the questions on the forums? [17:20] A good example of this is minimum requirements for an installation. [17:20] Your goal in this research is to ensure your documentation answers the most common questions end-users have. [17:20] Users should be able to reply to common questions with a link to a section in your documentation. [17:20] ==Propose an Outline== [17:21] This is the most essential method discussed in this session! [17:21] If you don't use anything else I've discussed today, please use an Outline when creating your documentation. [17:21] Outlines allow you to organize content without getting weighed down by details. [17:21] Outlines are much easier for others to review than pages of text. [17:21] It is easier to see if something is missing in an outline. [17:21] It is also easier to rearrange items in an outline and see how they flow. [17:21] man [17:22] interesting. [17:22] Remember that most users will not read your documentation from beginning to end. [17:22] They will pick out the titles of sections that are most relevant to whatever they have questions about. [17:22] This is why understanding your audience and tasks is so important. [17:23] When you know what information users are likely to need to look up quickly, it's easier to create sections that meet those needs. [17:23] The sections your documentation needs to contain will vary depending on the purpose of your documentation. [17:23] Generally, your documentation should contain an introductory section that explains what the application is in one or two sentences. [17:23] Your documentation should also contain an FAQ or troubleshooting section for addressing common problems. [17:23] Finally, your documentation should contain a link either to the project page for the application or to the Ubuntu forums for users who want more information than what is covered by the scope of your documentation. [17:24] If your topic is very complicated, your documentation should be grouped into sub-sections intended to address the different users. [17:24] For instance, the Packaging Guide contains a Basic section for new users and Advanced sections for users who have advanced or specific needs. [17:24] Remember to keep the documentation structure simple and easy to follow. [17:25] Again, readers will not read your document from beginning to end. [17:25] Make sure you clearly define sections to help readers who are looking for specific answers. [17:25] ==Submit to Doc Team== [17:25] I highly recommend you submit your documentation outline to the Doc team before you write a single word. [17:26] There is nothing worse than spending a lot of time on a section the team decides shouldn't be included in the final document. [17:26] Typically the folks reviewing your submission have a good understanding of how the documentation fits together as a whole. [17:26] Some topics in your outline might be better addressed in a section of the wiki whereas some are best suited for the system documentation. [17:27] The easiest way to submit your documentation is to create a sub-page in your own wiki name space on the Ubuntu wiki. [17:27] Then email the link to the mailing list and request a review. [17:27] For instance, my wiki space is https://wiki.ubuntu.com/AugustinaBlair [17:27] I typically post drafts under my namespace as follows: AugustinaBlair/MyDraftDocument [17:28] Wikis make it easy for team members to make changes and leave comments. [17:28] If you don't like the changes, you can roll them back. [17:28] The wiki is also web-based making it easier for folks on the team to access it wherever they are without downloading anything. [17:28] Thus, you are more likely to get more useful feedback! [17:29] ==When to Begin Writing== [17:29] Once you've gotten the ok on your outline from the team, you can start filling it out. [17:29] With all the previous research you've done, it should be really easy to fill in the remaining content! [17:29] That's all I have for discussing the pre-writing process. [17:30] A discussion on the actual writing itself is best saved for another session, but I'll leave you with some tips after the Q&A [17:30] ==Q&A== [17:30] If anyone has any questions, comments, etc, feel free! [17:31] I will leave this open for the next 15 minutes or so then end with some writing tips. [17:31] missaugustina: how long do you typically spend on the preparation and over what time period do you go expect to go through including getting feedback? [17:31] Well, it depends on the complexity of the topic. [17:31] I recommend spending at least a week on preparation. [17:32] Sometimes you need to walk away from something and come back to it after a 24 hour period so that you see it with fresh eyes. [17:32] You are more likely to see something you missed. [17:32] missaugustina: when you say "submit to the documentation team" does that mean link here or is there something more formal? [17:32] Once you submit your outline to the ubuntu-doc mailing list, expect it to take anywhere from a few days to a week. [17:32] I generally recommend waiting a week before proceeding. [17:33] Submitting documentation to the team is pretty informal. [17:33] I set up my wiki page under my namespace and send a link to the mailing list specifically requesting a review [17:33] I typically wait 1 week before moving forward so that everyone gets a chance to look at it. [17:34] You can also post the link here in the IRC channel. [17:34] You should always send it to the mailing list no matter what you do. Not everyone on the team gets on the IRC channel. [17:35] There isn't any written rule or formality that says you have to use the wiki for your submissions. [17:35] I have been using it and found it to be really helpful, so I'm just recommending that method. [17:36] Oh, I meant to post examples of the things I had been talking about: [17:36] https://wiki.ubuntu.com/AugustinaBlair/MakeUsbStartupDraft [17:36] missaugustina: I found the wiki easy when adding to your document [17:37] https://wiki.ubuntu.com/AugustinaBlair/PackagingGuidePersonas [17:37] The wiki is great. [17:37] You can subscribe to it so you get email updates when someone edits your work. [17:37] Since it's a wiki, people are less shy about editing it and adding suggestions. [17:38] When I was working on the Make USB documentation the team was helpful with adding items to my outline I had overlooked. [17:39] I know people also use Google documents. [17:39] Google docs doesn't have a version tracking system and it's hard to see who edited what and when. [17:42] Alright well if no one has anymore questions about anything I've discussed I'll end my session with some writing tips. [17:43] If you're viewing this session via the irc logs after the fact (or you're just really late getting into the room) feel free to email questions to the list or to me directly. [17:43] https://wiki.ubuntu.com/AugustinaBlair [17:43] My contact information is on my personal wiki page. [17:43] ==Writing Tips== [17:44] Disclaimer: These are not "official" Ubuntu Doc Project guidelines, just suggestions for writing better documentation. [17:44] Feel free to disregard any of the writing tips I suggest in the name of clarity [17:44] The goal of any documentation is to benefit the reader so in any situation where these suggestions detract from that, go with what's best for the reader! [17:44] 1. Avoid future tense [17:44] Ubuntu documentation is translated into a lot of languages and future tense is one of the most ambiguous to translate. [17:45] 2. Avoid the passive voice [17:45] Not only is it annoying for translators but the passive voice also obscures clarity. [17:45] Examples: [17:45] Passive: The files are created in the home directory. [17:45] Active: Application x creates the files in the home directory. [17:45] Which one do you think is more useful to the reader? [17:46] 3. Avoid extra words like "can" and "should". [17:46] Examples: [17:46] Don't: You can click on the button to open a new window. [17:46] Do: Click on the button to open a new window. [17:46] Don't: You should see the new window open on your screen. [17:47] Do: When the new window opens, perform some task. [17:47] 4. Use the imperative voice. Use simple sentences. [17:47] The imperative voice is the "command tense" in English. [17:48] Examples: [17:48] Close the window. Click the button. Do this. Don't do this. [17:48] I know this makes the writing sound boring, but it's a lot more useful than lengthy complicated sentences with "personality". [17:48] Readers aren't looking at documentation because they want to be entertained ;) [17:49] 5. Final Tip! Don't take criticism personally. [17:49] Also, only consider the criticism that is relevant to your document. [17:49] Experienced team members will likely offer developmental advice or wording advice with usability in mind. [17:49] Less experienced members are likely to dwell on spelling, word choice, or grammar suggestions. [17:50] Consider the feedback that is most relevant to the stage you are at :) [17:50] While you may take pride in your writing, consider that this isn't really *your* writing, it belongs to the community! [17:51] If you are disturbed by any feedback you get from anyone on the team, you should definitely discuss it with them privately. [17:51] More than likely it's just the result of the limitations of text-only communication, and not anything personal ;) [17:51] Ultimately, the best way to avoid confusion and to ensure quality feedback is to clarify the intent of your writing by using the methods I've discussed. [17:52] Feel free to offer any questions or comments :) [17:52] Phil Bull will be starting his talk in about 10 minutes I believe :) [17:52] missaugustina: I'll probably leave it until 18:30pm UTC [17:53] unless people are really keen to get started at 18:00? [17:53] OK! I pretty much finished and had some writing tips in the event there weren't too many questions. [17:53] So I'm done, unless anyone has further questions or comments regarding anything I've discussed. [17:54] Thanks Augustina, that was very helpful [17:54] philbull: I think you advertised 16:30 UTC so probably best to wait in case others turn up - much as I'd like to get back to bed for a bit (5am here) [17:55] thanks missaugustina [17:55] OK, I'll start at 18:30 UTC [17:55] if anyone can't wait until then, I've put the session online already: [17:55] yeah, 18:30. see - I'm not thinking yet [17:55] https://wiki.ubuntu.com/Philbull/MallardIntro [17:56] If you're staying around, you might want to download and extract the following: [17:56] https://wiki.ubuntu.com/Philbull?action=AttachFile&do=get&target=mallard.tar.gz [17:57] it's full of examples that I'm going to run through [18:05] https://wiki.ubuntu.com/AugustinaBlair/HowToWritingProcess [18:05] The notes from my session are here. Thanks everyone! === nigel_nb_ is now known as nigel_nb [18:31] Hi guys [18:31] I'm just about ready to start my session [18:31] Is everyone ready? [18:32] *** 1. Introduction *** [18:32] Welcome to this extra OpenWeek session from the Documentation Team. [18:32] I'm Phil Bull, and I'm going to be talking about writing documentation in an XML format. [18:32] The topic is "Mallard from scratch: Writing XML documentation for the GNOME desktop". [18:32] This session is aimed at people who have never written XML before, but would like to get involved with writing system documentation. [18:33] See https://wiki.ubuntu.com/DocumentationTeam for more information on contributing. [18:33] We'll be concentrating on Mallard. This is a new format which has specifically been developed for the GNOME Documentation project. [18:33] We're hoping that it will be pretty useful for other open source projects too! [18:33] I'm going to go through the material pretty quickly. I'll stop a couple of times during the session for questions, and I'll make the transcript available online. [18:34] There is also a tarball containing example files and a few exercises available from here: [18:34] https://wiki.ubuntu.com/Philbull?action=AttachFile&do=get&target=mallard.tar.gz [18:34] My Internet connection is acting up at the moment too, so if I get disconnected you can find a copy of the session here: [18:34] https://wiki.ubuntu.com/Philbull/MallardIntro [18:35] OK, let's begin! [18:35] *** 2. XML basics *** [18:35] I'll be introducing some basic XML concepts in this section. [18:36] *** 2.1 What is XML, why do we use it? *** [18:36] XML stands for "eXtensible Markup Language". [18:36] Markup languages are often used to give information on how parts of a text document should be displayed. [18:36] For example, HTML is an example of a markup language. With HTML, you can mark-up the text to tell the computer to display it in bold, or change the colour of it, for example. [18:38] So, markup languages let us add formatting and structure to a text document. [18:38] We want our documentation to have formatting and structure, so that's why we're interested in using a markup language. [18:39] But which markup language? For documentation, we're usually more interested in the structure than the formatting. The important thing is the content; a designer can format the document afterwards. [18:39] We also want to organise and link topics together easily (and automatically, if possible). Translation and outputting the document in multiple formats (such as HTML and PDF) are also desirable. [18:39] HTML isn't great for these things, so most technical writers use XML formats like DocBook and DITA. We're using Mallard, which is an XML markup language. [18:39] It provides a set of XML "elements" which let us define the structure and formatting of some text. [18:39] Once we've added these elements to the text, we can open the file in a viewer which understands the Mallard XML format. The end result is a help file, which your users can view and navigate on their computer screen. [18:40] See here for more information on what XML is: http://en.wikipedia.org/wiki/XML [18:40] *** 2.2. What is an element? *** [18:41] Elements are the building blocks of XML documents. [18:41] Here is an example of an element: [18:41]

Hello, World!

[18:42] The "

" is the start tag, and denotes the start of an element. The bit between the angle brackets (a "p" in this example) tells you what *type* of content the element contains. [18:42] Here,

means that the element contains a paragraph of text. Another example, , means that the element contains a link. There are lots of different elements that you can use. [18:43] The "

" is the end tag, and tells you when the content has finished. It is identical to the start tag, except for the forward slash. [18:43] The bit in between the start and end tags is the "content". It can be all sorts of things, such as text, a link or a filename to an image. [18:43] Whitespace (like spaces and new-lines) don't matter much in XML. You can have your start and end tags on different lines to the content, and the element will still be valid. For example, this: [18:43]

[18:43] Hello, World! [18:43]

[18:43] is exactly equivalent to the example I gave above. [18:44] Whitespace, no matter how much of it you have, is usually displayed as just a single space. This: [18:44]

[18:44] Hello, [18:44] World! [18:44]

[18:44] should be displayed as: [18:44] Hello, World! [18:45] Some elements don't have any content. These elements don't have a start and an end tag; instead, they have a combined tag, which looks like this: [18:45] [18:45] Note the forward slash at the end of the tag here. [18:45] We'll see lots of examples of different elements soon. [18:45] *** 2.3. Elements can contain other elements *** [18:46] Some elements can contain other elements! [18:46] This allows us to *nest* content, which is very important for structuring your document. [18:46] An obvious example is that you might have a paragraph,

, inside a section,

. [18:46] There are lots of other reasons why you might want to put one element inside another, though; for example, if you have some bold text in a paragraph, or if your section has a title. [18:47] *** 2.4. Only certain elements are allowed in other elements *** [18:47] XML is a very strict markup. HTML tends to be very forgiving if you put the wrong element in the wrong place, or miss an end tag. [18:47] Not so with Mallard. There are rigid rules for what is allowed where, and how it must be used. [18:48] This is actually a feature! By insisting that everyone follows a strict standard, you ensure consistency and compatibility. [18:48] This means that you will sometimes need to refer to the Mallard specification to see what is allowed. It's not difficult once you're used to it, though. [18:49] (I'll jam an appendix in at the end of this session, if anyone's interested in how to read the spec) [18:49] An important example of the strictness of the standard is that only certain elements are allowed in a given element. This makes sure that the structure of the document makes sense. [18:49] For example, the element cannot contain a . [18:50] Some elements have compulsory elements too. [18:50] For example, the
element *must* contain a element. [18:50] <philbull> *** 2.5. Elements can have attributes *** [18:51] <philbull> As well as content (the stuff in between the start and end tags), elements can have attributes. [18:51] <philbull> Attributes give extra information about an element. [18:51] <philbull> They are used for lots of things, such as identifying specific elements, defining the URLs of links and providing alternative text. [18:52] <philbull> Here is an example of an attribute: [18:52] <philbull> <section id="introduction"><title>Welcome!
[18:52] The name of the attribute is "id" and the value of it is "introduction". [18:53] Each element can have several attributes, but it can't have more than one attribute with the same name. [18:53] Some attributes are compulsory, or expect a value with a certain format. We'll see more examples of attributes soon. [18:53] *** 2.6. Examples *** [18:53] Has everyone downloaded the tarball of examples that I linked to earlier? [18:54] Here's the link again if you missed it: https://wiki.ubuntu.com/Philbull?action=AttachFile&do=get&target=mallard.tar.gz [18:54] philbull: looking at it now [18:54] awesome [18:54] Open the file Example-bad.page and see if you can identify what is wrong with the document. [18:54] It might take you a little while [18:54] Once you've had a go at correcting it, compare it with Example-good.page to see how you've done. [18:55] You can see a screenshot of how that page looks here: [18:55] https://wiki.ubuntu.com/Philbull?action=AttachFile&do=get&target=Example-Good.png [18:55] We'll take a break now for questions, and so that you can take a look at the examples [18:55] (BTW, let me know if I'm going too fast/slow/boring) [18:58] I'll start going again in a couple of minutes, if there are no questions [18:58] meeting? [18:59] ZachK_: yes, we're just in the middle of an OpenWeek session [18:59] philbull: ok..mind if i sit in? [18:59] Of course not, welcome! [18:59] philbull: i'm on the Ubuntu Doc Contributors page on LP.. [18:59] You can find a transcript here: https://wiki.ubuntu.com/Philbull/MallardIntro [18:59] philbull: what application do you use to read mallard? any xml reader or something specific to mallard? [19:00] anthropologist: to edit Mallard, I use a normal text editor, like gedit [19:00] SO WHAT!!!!! [19:00] =-O [19:00] To view Mallard, you can only use Yelp at the moment [19:01] I'll be going into that later [19:01] ZachK_: are you OK? [19:01] philbull: ah...why wouldn't i be === That_Wiki_Guy is now known as ZachK_ [19:02] sorry, just going back through the logs [19:02] OK, any more questions, guys? [19:02] philbull: ah........i'm confused [19:03] I might have missed some messages, my Internet connection is acting up [19:03] (feel free to resend if you think I missed something) [19:04] I don't think you missed anything phil. ZachK_ seemed to say SO WHAT!!!! to nothing [19:04] anthropologist: exactly.... [19:04] i'm the odd one...... [19:05] ZachK_: were you having 2 conversations at once? [19:05] OK, I'll wait a couple more minutes before I start again [19:05] anthropologist: ah no..... [19:06] *** 3. A simple Mallard document *** [19:06] Let's write a simple Mallard document for ourselves. [19:06] Go to the "first" directory in the "mallard" folder and open the file index.page in a text editor. [19:07] Everyone ready? [19:07] ready [19:09] I'll wait a couple of mins for IRC to sort itself out [19:12] ok, i'll have to carry on [19:12] *** 3.1. The page element *** [19:12] At the top of the file you will see a page element with three attributes. [19:12] The xmlns describes what type of XML document we are using. [19:12] The type gives the type of page, which can be either "guide" or "topic". We'll discuss these more later. [19:12] The id is required, and is a unique identifier for this page in the document (more on that later, too). [19:12] For now, leave it as "index". [19:13] *** 3.2. The info section *** [19:13] The info section provides information about the document, such as its version and who wrote it. [19:14] You can put lots of different types of information in this section, but we're normally only interested in a couple of things. [19:14] So, let's make this document our own. Change the revision date to todays date, and bump the version up to "1.1". [19:15] Change the name and email address of the author too. [19:15] This document is your copyright, so lets add some copyright information. [19:15] Somewhere in between the start and end tags, add a element, with two elements inside it, and . Add appropriate content. [19:15] Don't forget to add an end tag for too! [19:16] *** 3.3. The title and description *** [19:17] After the info section has been completed, we can start writing the document itself. [19:17] Every document needs a title, so let's add a element after the info end tag "</info>". [19:17] <philbull> Titles should be short but descriptive. Avoid unnecessary words! [19:18] <philbull> In Mallard, we also give slightly longer descriptions of pages to supplement the title. The description should elaborate on the title, but not repeat it. [19:18] <philbull> It's also a good place to use synonyms of the key words in the title, to help people searching for certain terms to find the right article. [19:19] <philbull> Here's an example: [19:19] <philbull> Title: Change the color of highlighted text [19:19] <philbull> Description: Change the background color of text which has been selected with the mouse. [19:19] <philbull> Use the <desc> element to add a description. This element belongs inside the <info> section, not outside it like the <title> element. [19:19] <philbull> *** 3.4. A section *** [19:20] <philbull> Sections are used to structure longer pages. [19:20] <philbull> Mallard is designed for "topic-based" help; each page in a Mallard document should cover one topic and nothing more. [19:20] <philbull> It's not like writing a book, where sections flow from one to the next. Each page should stand on its own, although of course you can link to other topics. [19:20] <philbull> As such, you shouldn't need to use sections all of the time, since your topics should be reasonably concise. [19:20] <philbull> I've found that many of the topics that I've written aren't long enough to be split into sections. [19:21] <philbull> Anyway, you'll need them for longer pages. [19:21] <philbull> You can add a section just by using the <section> element, anywhere below <title>. You can add as many sections as you like to a document. [19:21] <philbull> Remember to give each section its own <title>, which must be in between the start and end tags of the <section> element. [19:22] <philbull> *** 3.5. A section with some paragraphs *** [19:22] <philbull> There's not much point having an empty section, so let's add some paragraphs of text. [19:22] <philbull> This is as easy as adding <p> elements into the section. [19:22] <philbull> You can add as many <p> elements as you like. [19:23] <philbull> *** 3.6. A paragraph with italic text *** [19:24] <philbull> All of the elements that we've used so far have been "block" elements or non-displaying elements. [19:24] <philbull> Block elements, such as tables and lists, occupy a paragraph of their own. They can be thought of as the building blocks of a page. [19:24] <philbull> Non-displaying elements, like most of the elements in the <info> section, aren't displayed on the page itself. They might be displayed on an "About this document" page, though. [19:24] <philbull> Another type of element is an "inline" element. Inline elements are used to markup parts of a string of text, but necessarily the whole string. [19:24] <philbull> They are used for adding links, making text bold and so on. [19:24] <philbull> Here's an example of making text italic: [19:24] <philbull> <p>Some of the text here is <em>italic</em>, but none is bold.</p> [19:24] <philbull> The <em> (emphasis) element is used to make text italic. [19:25] <philbull> You can't make text bold at the moment, because Shaun McCance (the author of Mallard) hates bold fonts. [19:25] <philbull> *** 3.7. The end of the document *** [19:25] <philbull> The end of the document is simply the page end tag, </page>. [19:26] <philbull> To summarise, we have: [19:26] <philbull> The page start tag, <page> [19:26] <philbull> The <info> section. [19:26] <philbull> The <title>. [19:26] <philbull> The contents of the page, which might be <section>s, <p>s, or other block elements. [19:26] <philbull> Maybe some inline elements inside the block elements. [19:26] <philbull> The page end tag, </page>. [19:27] <philbull> Compare your document with index.page in the "example1" folder. Are all of the tags in the right places? [19:27] <philbull> *** 3.8. Displaying the document in Yelp *** [19:27] <philbull> What good is the document if we can't display it? [19:27] <philbull> At the moment, the only help viewer which has been modified to work properly with Mallard documents is Yelp, the GNOME help viewer. [19:28] <philbull> You can convert Mallard docs to HTML, though. [19:28] <philbull> To view Mallard docs, you need the versions of gnome-doc-utils and yelp which are included with Ubuntu 9.10. If you don't have 9.10, you can compile them from source yourself. [19:28] <philbull> That's left as an exercise for the reader, though... [19:28] <philbull> To open your Mallard document in Yelp: [19:28] <philbull> Open a Terminal and change to the directory that your index.page is in, e.g. [19:28] <philbull> cd /home/phil/mallard/first [19:29] <philbull> Then, type the following and hit return: [19:29] <philbull> yelp $PWD [19:29] <philbull> Yelp looks for a .page document in the current directory which has the ID "index". [19:29] <philbull> If your document is valid Mallard XML, you should now see something like this: [19:29] <philbull> https://wiki.ubuntu.com/Philbull?action=AttachFile&do=get&target=example1.png [19:29] <philbull> If not, look at any messages which might have appeared in the terminal. These might give you some idea of what is wrong with the document. [19:29] <philbull> OK, I'll stop again for questions. [19:29] <philbull> Is anyone having problems? [19:31] <anthropologist> all good [19:32] <philbull> ok, I'll start again [19:32] <philbull> *** 4. Other Mallard elements *** [19:32] <philbull> (I'll go through this one quickly, just for reference) [19:33] <philbull> There are lots of useful elements that you can use in Mallard. I'm going to briefly go through a few of the more common ones. [19:33] <philbull> You can find some examples in the "elements" folder. [19:33] <philbull> *** 4.1. Lists *** [19:33] <philbull> There are several different types of list. For a full listing of them: http://www.gnome.org/~shaunm/mallard/mal_block.html#lists [19:33] <philbull> The most important one is probably <steps>. This is used for procedural instructions, like the steps in a how-to. [19:33] <philbull> You start the list with the <steps> start tag, and then put in as many steps as you like using the <item> element. [19:33] <philbull> Each <item> element *must* contain one or more block elements, usually a single paragraph, <p>. [19:33] <philbull> You can put other block elements in there, like an image or even another list! [19:34] <philbull> It's best to keep lists simple, though. Complicated lists are difficult to read. [19:34] <philbull> I've put lots of examples in the "elements" folder. [19:34] <philbull> One last thing to note is that lots of people forget that you need to put a block element in the <item> element. This is right: [19:34] <philbull> <item><p>A list item.</p></item> [19:34] <philbull> This is wrong: [19:34] <philbull> <item>A list item.</item> [19:34] <philbull> *** 4.2. Links *** [19:34] <philbull> Mallard has some interesting linking features, but we're going to concentrate on simple inline linking for now. [19:34] <philbull> These links are displayed like hyperlinks on webpages; the content of the <link> element is clickable. [19:34] <philbull> The <link> must have a "xref" or "href" attribute. These give the address which is opened when the link is clicked. [19:34] <philbull> If you want to link to a webpage, use the href attribute. For example: [19:34] <philbull> <p>Visit the <link href="http://www.ubuntu.com">Ubuntu</link> website for more info.</p> [19:35] <philbull> You can also link to a different section on a page, or a different page in a document. Use the xref attribute for this: [19:35] <philbull> <p>See the <link xref="intro#overview">introduction</link> for a brief overview.</p> [19:35] <philbull> The "intro" part is the ID of the page that you want to link to (remember the ID attribute of the <page> element?) [19:35] <philbull> The "overview" part is the ID of a section in the intro page. The "#" separates the two. [19:35] <philbull> If you want to link to a section in the same document as the link, just miss out the bit before the "#": [19:35] <philbull> <p>The final section of this introduction is an <link xref="#overview">overview</link>.</p> [19:35] <philbull> In this case, you would have a section start tag that looks like: [19:35] <philbull> <section id="overview"> [19:35] <philbull> *** 4.3. GUI elements *** [19:35] <philbull> When you refer to part of a graphical user interface in some instructions, use the <gui> element. [19:36] <philbull> This is most commonly used for buttons and labels. [19:36] <philbull> Here's an example: [19:36] <philbull> <p>Click <gui>Save</gui> and then close the document</p> [19:36] <philbull> *** 4.4. GUI menus *** [19:36] <philbull> When you refer to a list of buttons in a user interface with <gui>, like in a menu, use the <guiseq> element to group them together. [19:36] <philbull> In Yelp, this results in the buttons being displayed with nice arrows in between them. For example, this: [19:36] <philbull> <p>Click <guiseq><gui>System</gui><gui>Help and Support</gui></guiseq> to get more help.</p> [19:36] <philbull> will be displayed something like this: [19:36] <philbull> Click System -> Help and Support to get more help. [19:36] <philbull> *** 4.5. Summary of others *** [19:37] <philbull> There are lots of other useful elements. [19:37] <philbull> Take a look at the spec for more information: [19:37] <philbull> http://www.gnome.org/~shaunm/mallard/spec.html [19:37] <philbull> OK, thanks for staying with me so far, guys. [19:37] <philbull> This is the last section now... [19:38] <philbull> *** 5. Multi-page documents *** [19:38] <philbull> One of the strengths of Mallard is the ease with which you can organise information. [19:38] <philbull> This is done by putting each topic on a separate page, and then linking the topics together into a document. [19:39] <philbull> *** 5.1. Structuring a document *** [19:39] <philbull> The main aim of structuring a document is to put information where your readers are expecting to find it. [19:39] <philbull> This means that they can get the information that they want quickly, and solve their problem with the minimum of fuss. The best help files are often the ones that users spend the least time reading. [19:39] <philbull> Normally, this means that you will want to split information into self-contained topics. Each topic is displayed on a page of its own. [19:39] <philbull> You also need some way of navigating between these pages, or grouping them together when they are about similar things. [19:39] <philbull> To help you with this, there are three types of page in Mallard. [19:40] <skiquel> and you people should learn to show respect. [19:40] <skiquel> jk [19:40] <skiquel> also wrong channel, sorry :-) [19:40] <philbull> *** 5.2. The "index" page *** [19:40] <philbull> The index page is the "first" page in the document. When a user clicks Help -> Contents, this is probably what they will see. [19:40] <philbull> The purpose of this page is to provide a starting point for people to go looking for the information that they need. [19:41] <philbull> As such, the index page will normally just be full of links. [19:41] <philbull> You won't have to put these links in by yourself, though! Mallard pages can automatically link themselves in to the index page. [19:41] <philbull> The index page has the <page> element with attributes "id" with value "index" and "type" with value "guide". [19:41] <philbull> When you try to open a document in Yelp (see section 3.8), it will look for a .page file with the ID "index". [19:42] <philbull> *** 5.3. Guide pages *** [19:42] <philbull> The index page is a "guide" page. You can have other guide pages too, though. [19:42] <philbull> A guide page is one which collects together links to similar topics, sort of like displaying the contents of just one chapter of a book (rather than the whole table of contents). [19:42] <philbull> As with the index page, other pages (including other guides) can automatically link themselves into a guide page. [19:42] <philbull> Guide page <page> elements can have almost any ID that you like, but must have type="guide". [19:42] <philbull> See http://www.gnome.org/~shaunm/mallard/mal_page.html#guide [19:43] <philbull> *** 5.4. Topic pages *** [19:43] <philbull> Topic pages are where you provide instructions or explain concepts. They are where the user reads the information they are looking for. [19:43] <philbull> Most of your pages will be topic pages. [19:43] <philbull> Topic pages can link themselves into guide pages, as mentioned before. [19:43] <philbull> Topic pages have <page> with type="topic". [19:43] <philbull> See http://www.gnome.org/~shaunm/mallard/mal_page.html#topic [19:44] <philbull> *** 5.5. What are reciprocal links? *** [19:44] <philbull> Reciprocal links are a pretty cool feature of Mallard. [19:44] <philbull> If you link to topic A from topic B, then topic A will automatically have a link to B added at the bottom of the page. [19:44] <philbull> This is useful because it helps the reader to navigate between topics, and makes it easy to extend a document by simply plugging pages into it, without needing to modify any of the other pages. [19:44] <philbull> *** 5.6. Linking a page into a guide *** [19:44] <philbull> To link a topic page into a guide, you need to add a <link> element into the <info> section of that topic page. [19:44] <philbull> You *don't* need to put a link element into the guide page. [19:44] <philbull> This <link> element is similar to the inline <link> element. This time, however, it can go anywhere inside the <info> element. [19:45] <philbull> Now, it's a single "combined" tag, rather than an element with a start and end tag and some content: [19:45] <philbull> <link type="guide" xref="index#behavior"/> [19:45] <philbull> The "type" tells Mallard how to link the topic into the guide ("guide" just means to include it as a normal link). [19:45] <philbull> The "xref" is similar to the xref in section 4.2, but it tells you where the link will *appear*, not where it is linking to. [19:45] <philbull> In this example, the link will appear in a section with id="behavior" in the index page. [19:46] <philbull> *** 5.7. Linking guides to other guides *** [19:46] <philbull> Guides are linked in to other guides just as topics are linked into guides. [19:46] <philbull> Just use the <link> element in the <info> section, as above. [19:47] <philbull> *** 6. Where next? *** [19:47] <philbull> OK, that's the end guys! [19:47] <philbull> If you're interested in working with Mallard, get in touch! [19:48] <philbull> philbull AT gmail DOT com [19:48] <anthropologist> thanks phil [19:48] <philbull> If you missed any of the session, it's all here: [19:48] <philbull> https://wiki.ubuntu.com/Philbull/MallardIntro [19:48] <philbull> anthropologist: that's OK, I hope it was useful [19:48] <philbull> Does anyone have any questions? [19:50] <anthropologist> nothing from me. I'll probably have some if/when I try using it. I notice that the mallard guide isn't complete yet. [19:50] <philbull> that's true [19:51] <philbull> We'll hopefully have it completed in the next month or two [19:51] <philbull> It would be very useful for newcomers! [19:51] <philbull> I'll try to spend some time on it over the next month or so [19:52] <philbull> OK guys, last chance for questions... === popey_ is now known as popey [19:55] <philbull> Thanks everyone who turned up. [19:55] <philbull> Let me know if you have questions === SpacePigeon is now known as TheBogey