 We're in the next half an hour. You're going to hear a lot of stuff about documentation and single sourcing dita conditional texts and more of that wild stuff The first introduced myself. I'm Christophe van Tomen. I'm the co-founder of Pronovix, which is a Hungarian Belgian company And we've been working with we started to work on dita It's which is an XML standard for Single-sourced documentation, and I'm going to explain you in a minute what that exactly means and what it has to do with Drupal I took this slide because And I went back to the Linux world because the the icons are just sexier But this is where we are heading basically a bunch of distributions that are Reusing much of the same stuff And then like a couple of Contrib modules that are being used in a bunch of distributions and all of them are making their own documentation All of them separately. None of them are really well, there's going to be some collaboration But in the end if you want to Document a distribution you're starting from scratch every single time and that's just insanity because there's this really cool technology called single sourcing and With single sourcing what you basically do is that instead of trying to build one book You're building individual topics Like small pieces of contents that you can reuse and and the core there is minimalism So instead of and and structure so instead of trying to like make one fluid text that describes your whole Project you you create small pieces that can be reused in different in different outlines in different maps The cool thing is also that you can use it in different contexts So you can use the same topic in help in the online documentation in a bunch of other stuff and You can publish it to different formats. So like e-pop Kindle and so on and so on Now today the the kind of industry standard for for single sourced Publication for of technical documentation is Dita. Dita is an open standard It stands for Darwin information type architecture. It has nothing to do with With ladies in champagne glasses. That's what you find when you look at the first time for Dita It's a very serious standards that originated at IBM that they open sourced that they opened up through the Oasis committee through an Oasis committee and It has a couple of very interesting structures that I think we could use also in Drupal's documentation one its topic oriented So instead of having one outline one like, you know, this is the way it should all be organized You're you've got individual topics. They've got maps. They're separate from the topics They allow you to take it one Yeah, it's the outline So like instead of like in a book module where you have only one outline you can have as many as you want You want your own outline? Go ahead make it They got con ref which is an interesting technology for like Transclusion you take a piece of text from here. You plug it into another place Conditional text I will get back to that in a second which is like, okay If you're on a Windows machine, you need to read this if you're on a Mac You need to do this and and being able to switch between those So that you can like show the right content to the right person, which is very important And then a bunch of metadata, but that's not all that fancy. We also have that in Drupal Very very short Dita has like three main structural elements So actually for including the outlines which are called Dita maps you got tasks which are like You know, this is how you do it. So how to with steps you got concepts which are like explanations of a certain Thing whichever that is could be like notes and you got references and references reference topics are The like the API documentation for example and Dita allows you to do specializations and stuff But I'm not gonna go in there. It's really cool. Really fancy now We've got one problem else well next to next to Creating a better workflow for our Drupal documentation for the project We've got another problem or a lot of Drupal shops have another problem, which is documentation of their products When you create a site for someone You're kind of supposed to give them documentation about that site and In a lot of cases like we're guilty as charged In a lot of cases you just don't have the time or the budgets for doing that And and there's there's a couple of other like there's there's a lot of good reasons why it never happens like people Probably will just go and do a screencast which is okay, but we could do it. We could do better We could do much better Than that and this is kind of what what I imagine that's we could do with the Drupal documentation and with our project documentation instead of having a bunch of Really altruistic people that are spending a ton of their time Without getting as much recognition for it as like the the developers because you know developers are king But like we've got these team of people in in Drupal that are making documentation spending a ton of effort on it and But it's like, you know, everybody should be doing documentation. It shouldn't be just a small team that is doing that And basically if you use data with this topic based architecture You could use the same topics for your documentation for your customers as you're using for Drupal org You could use the exact same documentation you could reuse that so Topics could become something like modules that people collaborate on and that people work together on and contributes back to When they're creating their documentation for their customers And there's a there's a bunch of other stuff, but I won't go too deep in detail there But I think I want to hand over the word now First time I show you or Yeah, okay So Jennifer is going to talk a little bit about the the core help initiative and Yeah, just go ahead and What what's tamash and then tamash will come to present his Google summer of coach about conditional text and Something that we've been doing in our company with With outlines an outline system that is not bound to like, you know, you got one book outline No, you can have as many as you want Sorry, we only have one microphone here if we've asked for another one that hasn't come yet So I want to talk a little bit about what this means for Drupal and hopefully Drupal 8 so as Christoph was talking about what we'd like to be able to do is have a situation where if you made Well, we might have a new site called help dot Drupal dot org or it might be on Drupal dot org That's still under question But in Drupal dot org or help dot Drupal dot org would be using a bunch of different tools that I want to talk about for just a second To make some sort of curated official help and this would be for the inline help that's inside of Drupal So, you know, if you install Drupal you would get you could pull this into your site And then you could build some custom site help if you're a site builder and then you would have Just the help that's relevant to that site so the idea is for instance You know, there's there's some help for the block module that explains how to create a block how to Different tasks that you would do with the block module create a block place the block on the page And then maybe if you're using the context module you might not want to Use that helps page that says how to place blocks using the block module because you're using the context module for that So you could turn that page off and put a different one in it in the outline in its place for your site. Yes Yes, well, that's another that's another thing so You need to have yeah, what you're saying you need to make different outlines for the different roles on the site So if you are a just a content editor and you don't have permission to do the context module or the block module then you would want to be just using the content editor Outlines and you could make it so that the outline for how to manage the blocks and things on the page is not Available to the role that can't do that That's an excellent idea that we need to note. I will make a note of that. Can you make a note of that? Yeah, that's a really good point. So Yeah, so the question is can we make it so that the help for the block module would know that Say the task for adding a block would only be visible to people who have permission to add a block so that the task Help would use the same access system as the task itself. So that's an excellent excellent idea So we basically need to have a permission field on a task Excellent We're gonna have a bop later on I'll show the slide and we want to have some more discussion about this So anyway, the pieces that we have envisioned so far for the Drupal 8 inline help are First of all conditional text and I just want to talk a little bit about each of these so you know what the terms mean Christoph talked about it briefly But the idea of conditional text is that when you're writing say your task of how to add a block in Drupal 6 you went to administer Site building blocks and then add block in Drupal 7. It's under structure blocks ad block You want to use the same but basically a task is the same once you get to the ad block page And there's no sense really having two pieces of content that both say how to do this one for Drupal 6 and one for Drupal 7 And so what you want to do is you want to have a little tag in the top of your Text that you're writing that says for Drupal 6 go here for Drupal 7 go there and then the rest of the page could be exactly the same because the task is the same no matter which System you're in and what you can do that with conditional text and Tamash is going to actually Tamash worked all summer as a Google summer of code student and built a conditional text module which works great And I think is about to have a first beta release or may just have had anyway just about to have a beta release So that's what conditional text is about in brief help entities we don't want the help topics to be nodes particularly because Nodes do all sorts of things in the site. They're your main content They're visible usually to everybody that unless you've got some special content permissions module they Participate in RSS feeds. They have you know, they're on the on your taxonomy page. You probably don't really want your help pages to be Nodes per se because they're kind of a separate thing That's probably only for administrators or certain types of users on your site or they might not be But you want to be able to control them in a different way than normal nodes So you want to have help entities and if we're using sort of these data topics We want to have entities and fields that are specific to those entity types That's not really hard to do and it's kind of all been thought out that we just have to build it contextual linking you want to be able to link one help topic to another you probably want to have some kind of universal ID so that you're not Rebuilding things you also want to be able to when you're on the ad block page if you want some help You want to be able to click somewhere and get to the ad help topic so you want to have contextual linking between Pages on your Drupal site and these help topics and and vice versa You know why not have a link in your help topic that says open up the ad block page and you click on it And it opens it up. You know you can do that in in your Windows Microsoft Office help if you're in a Microsoft Office help and you click on something It will actually take you back to office and and get you right to the screen where it does that task Why can't we do that? I mean, it's all H2. It's all in Drupal. We should be able to link back and forth So that's kind of contextual linking and then multiple outlines Christopher already talked about that and we have start I guess of a module just that you're going to demonstrate also To that will build little outlines as opposed to the book module where when you create a node You put it you tell it what the parent page is. There's no concept of having a parent page You just want to have outlines that are flexible. Yes Each outline would probably be an entity One one like a node but another type of entity so you could make multiple outlines and you could give different permissions to different outlines and and outline could be Different steps in one larger task and each step was a little task topic or it could be even bigger than that You know, you can go back back out as many levels of abstraction as you need it could be the outline could be things that a content administrator needs to do on the site and it would have a link to the Block, you know the the adding new content finding content editing content or whatever else, you know, whatever else it needs to be So it's flexible though. I mean an outline could be something completely different I don't know what you know what you might need for your site But but generally it's going to be links to topics that are either concepts or tasks or reference material for So that somebody can gain an understanding and do things on the site Okay, and then again, you know just to stress this the idea is all of these topics that are sort of canned and curated and You know built by the documentation team, which hopefully includes everybody We'll live on Drupal.org or help dot Drupal.org or some way and then we want to have a client server architecture So that when you're building a Drupal site, you can go and pull in the topics that you need which could be for contributed modules or core or whatever and Build your site help from things that you write that are specific to what you built plus the the curated help that we have and also I didn't mention on here, but translated Okay, I'll just mention that you know Drupal's international and and the help documents themselves need to be translated by the same translation team that does Drupal and Instead of having them being embedded in the Drupal code as they are now Having them on pages will actually help the translators be able to comprehend what they're translating So just briefly on the topic types Just I've talked about the basic data topic types We want to kind of expand those and have a couple of custom types for Drupal the task and the concept ones are that are from data. We actually want to have probably have a specific Topic type called a glossary item and that way you could have things like you know Underline the glossary words when you're viewing help and you could have a little pop-up that tells you what the definition of node is Although we're not using node in Drupal 7 but block for instance You can have a definition for block and anytime block appears in the help You could have a little text filter that automatically made that into a link in a pop-up topic Then you can also have a glossary that could be built a to z as another navigational aid or a search A module overview would be another type of a it would be a reference type of topic But a special one which would be an overview of what a module does and a link to all the tasks that you can accomplish with that module Reference we as a standard data one and then contextual would be another topic type Which probably wouldn't appear in outlines and indexes, but these would be the contextual help for particular sections on particular pages like a field level help on a on the ad block field They might have a little question mark next to the field and a little pop-up item that could come just for that field So that would be a little contextual help item that wouldn't appear in an outline anywhere But it's still very useful to have and you probably want that to be a separate topic type so that it's separated out in the in the editing and in the in the help building and Just as a little status report as I mentioned the conditional text module has been built outlines At least we have a beta version probably needs a few more features outlines preliminary development entities That's pretty easy to do. We have a design for them. You just have to build the fields and so on If we're going to put it in core We will need a reference field in core because I mean most topics are going to have a list of related topics That's obviously like a node reference, but entity reference So we're going to need a reference module in core if we're going to put this in core Contextual linking and navigation still in the design phase. We need to do some more thinking client server Way early in the design phase that hasn't even been thought out But I mean we have models for other things that we can go out to a server and get stuff like the update update status for modules we do that and also the Translations if you import a new module and you've got a French and English site You're going to get the French and English translation. So we have models for that. It just needs to be thought through Then we need to think about actually how to integrate Translating these help topics with the localized at Drupal dot org site because that's where the translation teams are haven't thought through that and Some editing permissions. So for instance, if you're the maintainer of the views module and you want to do your help on in this Hopefully good enough help system that you won't need to use the advanced help module or whatever anymore the You might want to say that only certain people in your project have permission to edit your help And we need to think through the permissions on help dot Drupal dot org or whatever it is for Editing the help documents on a per project basis And this there's a page which I should have put up a link for I'll find it On Drupal dot org. There's a page that outlines the this Whole idea for the Drupal help system in more detail So I'll just conclude by saying we have a couple buffs scheduled tomorrow at 3 p.m. There's a Dita buff that Kristoff will be leaving and then I guess the buffs are over in another building somewhere and on Thursday at noon We're gonna have a brainstorm about Help and documentation and that's going to be during lunchtime So I'll turn it over to Tamash for a quick demo of the modules So the next thing you'll see is the outline Do you know how So basically What we wanted to do was something like a Dita map. So the idea is that you can you can Take a topic Whatever topic could be any of these entities that the jennifer just explained about And drop them into a map and then drag and drop them Yeah map being outlined There's there's so much name confusion um So and and um because in Dita it's called Dita map. That's why Yeah We're getting there So and um Um Okay So Can can you go a bit down? Okay So and basically what you see here This is a part of a product that we're building which is using some of the similar concepts of of topic reuse and maps um So and this is the the map or the outline entity Where you got a title and here you got an autocomplete field where you can just look for a specific topic And you can add it and then once you add it it comes into your drag and drop list This is a reuse from the menu system, right? Tamash, do you want to explain? Yes I'll give it to you. Okay, so this is uh This is based on heavily on the menu system of Drupal. So if you see the menu interface, this is the same. It's using Uh an api quote table drag and then with that you can easily Reorder stuff And you can put it So you can actually build an old line tree which could be interesting if you are doing like a book or something However, currently what we have now As an output format is just power point Okay, so the thing is that uh We could also do it with uh, so this is just an interface and there's also an api for that to add topics here Uh javascript api so it's works with faceted search for example So you uh, so with this kind of stuff you can really quickly just put together a document uh From your existing content pieces Okay I show the conditional text Um, okay, uh, I've created two examples for for conditional text uh, the first one Is uh when you have a different module So this is a this is a help text of the bright cove module It's copy pasted from the bright cove modules help page And if you see that uh, you can have certain parts enabled or disabled based on Which modules you have installed so for example if you have used installed and this text field would be open by default Same for media There's a drupal core specific uh texts here like you have a Help text for drupal 6 and you have help text also for drupal 7 It's quite easy to write The syntax is very uh simple So This is I just say that condition enabled views and then this to this display between the condition text Will be only displayed if you have used enabled um another case is uh Is when you want to display uh text for just certain roles then uh we could uh We could also made it possible with this kind of uh Conditions So you can say that you just so a user can say that he is like a Developer and then only the text for developers will be visible Uh, I just quickly show the configuration page for it What you have to do is to create a text format And that conditional text and then you could create this custom values Oh So Yes Um Where you can create a custom group which has values and those values are true for certain uh user Groups and you could also say that for the Modules that you have certain modules enabled on your site So it's possible that that the help site uh could say that it has used while it doesn't have Or something like this I think I finished great So anyway, I think we're kind of out of time, but we will have uh two buffs later in the week to talk more about these topics and I don't I guess we didn't leave enough time for discussions But we probably have time for one question if anybody has one Or we can just conclude. Yes What's that video inclusion Right, so the question is how could you incorporate videos and I guess the answer that I would give is that um Within a given help topic. It's just an ordinary node or entity And so you just whatever technology you have for including videos in a node or an entity You could use the same thing. So the media module for instance. Yeah Any other questions? Yes in the back Oh, so uh, okay. So the question is is there some form of canonical outline that you could use to grow the The help outlines out for your site. I guess so the answer is yes I mean the help outlines will be entities that you could also import from the server So you could start with the help outline that we would provide or the help outlines We would provide and then add your own or you know modify them in some way So I think we better stop here and let the next speaker go But thanks for your attention and I did find the oh if you go and um Look in the community initiatives Core improvement section. There's a section on the new help system in that and that part of Drupal.org if you're interested in reading more Details also. Thank you