Hello everyone and welcome to Entrepreneur India's Smart Investing Series. We are kickstarting this very special series today with a timely topic of investing safely during COVID-19. The main purpose of this series is to provide our audience with useful tips on how they can invest and manage their money to grow their wealth. I'm Shipra and I'll be moderating this very interesting panel. We have put together to discuss how investors can navigate the choppy markets, stay the course with their goals and manage their investments during COVID-19. So let me lay the ground rule for our attendees. We please request you to attend the webinar from a quite room or an office with headphones and sit in an area with maximum internet signal to avoid any lag during the webinar. Post a 30 minute discussion with our speakers. We will be holding a Q&A session for all the attendees. So the attendees who are willing to ask questions will be automatically unmuted and will be asked to ask their questions. If you want to ask submit your questions, please do so in the Q&A box present at the below of the screen. We will spend approximately 15 minutes at the end of the session to answer questions. So before that, please hear our speakers intently and be ready with your questions. So to open the Q&A box, you can click on the Q&A box and you can submit your question there. Okay, so let me start by introducing our speakers. We have with us today Shri Khan Subramanian who heads private wealth investments and advisory practice at Kotak Investment Advisors Limited. Additionally, he supervises the wealth advisory desk across the international markets of Singapore, London and the US. Shri Khan joined the Kotak Mahindra Group in 2001 and in close to two decades with the firm he has worked across businesses and functions including life insurance, wealth management and investment advisory. Shri Khan has also been a member of the working group on SEBI regulations in 2009. Our second speaker is Rahul Jain. He heads the wealth management business for salary professionals and H&Is at Edelweiss wealth management. He started his journey with Edelweiss in 2008 as a zonal business head and has since then grown multiple levels to building and heading a business unit. Rahul has been instrumental in integrating two businesses of Edelweiss financial advisor and client advisory services into Edelweiss personal wealth advisory. A firm believer of customer centricity, he has been credited for involving a retail advisory business into a full-fledged wealth management business. I am delighted to welcome all the speakers. Thank you very much for joining us today. So let me start the discussion with the topic which right now concerns most of the salaried individuals. With businesses disrupted due to the virus due to COVID-19, salaried individuals are taking salary cuts as much as 60%. Appraisals have been shelved and of course jobs are being lost. So you know all this can be a major setback for investments and financial goals of individual investors. So let me start with you Shrikanth. How do you suggest that individuals can manage their investments so that their financial goals don't suffer in the long run even if they are taking a salary cut? Well, thanks Shrikanth and also welcome to Rahul, my co-panelist and also to all the audience. I hope I'm audible Shrikanth. Yeah, yeah, you're audible. No, it's an interesting question and I do agree with you that most of the salaried professionals have seen it fairly difficult as far as the current era of COVID is concerned. My limited two bits of advice to everyone would be that as much as possible do not derail from the discipline of investment that you've created. But that also means that it should not get precedence over any kind of borrowing that you may be tempted to make. I think in the long run what is absolutely crucial is that all of us learn to live within our means. So earlier if I were to get 100 rupees as my salary income and I was able to meet my lifestyle expenses and all my other expenses in about 60, 70 rupees and the balance 20 to 30 rupees is something that I was investing. And if there is any possibility to invest anything within that 20 to 30 rupees, we should continue to invest. But if it has gone, if for some unfortunate reason, the expenses have not gone down as much, but the salary has gone down more than I think do not worry. Right now hold tight, have your expenses to the bare minimum as possible, try not to take any unforeseen loans that you may be tempted to take as easy thing. And once it is over, come back to the discipline of investing and if there are any chances, because what has happened is while your income levels have dropped. For most of us, I'm also a salary professional. For most of us, our expenses have also dropped considerably, whether it's to do with the fuel expense, whether it's to do with any other kind of entertainment, eating out, leisure. So most of those expenses have also come off. So I think it is time that we take a hard look at our expenses, make it a very strongly disciplined personal balance sheet of ours. And if there is any IOTA of possibility of continuing the investment, I would strongly recommend, but not at the cost of taking any borrowings. Yeah, you said it rightly, Shri Khan that even if our salaries have gone down so have our expenses, you know, especially when we were in a strict lockdown, we practically had no avenue to spend except for utilities and everything else. Rahul, what would you like to add here? So I think I largely agree with the point that Shri Khan said, but since Shri Khan has already spoken about investments, I think if you look from financial goals point of view, the current environment, your growth rate, inflation, all are very important part that you make your plans because that is how you evaluate current value and future value, time horizon of investments. But I think in this whole pandemic, one thing which is also coming out very clearly, which was your basic question also about the salary cuts, uncertainty of jobs, etc, which are there. I think keeping that into mind, there are certain things which I would like to advise to the viewers and attendees. One is that since this is now like a hanging sword in your head, there can be a job cut, etc. If you have a contingency plan, a contingency fund which should be there, at least six months of expenses should be in a contingency fund. It should be in a liquid fund on an FD. I think it's a good time where you have to reprioritize your goals. So certain goals are very important like your child education. So that should be adequately, you should have money around the same. But there are discretionary goals also like buying a car which can be deep prioritized, that is second. Third is what Srikant also said that the expenses have gone down. But yes, you should also be very clear that your discretionary expenses should be reduced, that is the third one. And fourth is that I think it's a good time to reassess your risk profile because your risk profile is like willingness and your ability. And right now the ability really goes on because your job is uncertain, your salary cut is happening, which reduces your ability to take a risk. And obviously this time you would have also reassessed your abilities, how much you can manage the risk in the current environment would be a good reflection for you. So these are three or four points which you should consider while thinking about your investments in such current scenario of pandemic, etc. Yeah, a very relevant point, Rahul. In fact, about the financial risk, I would like to revisit this again later. But let me start with the specifics of investing. So this is about how to manage your overall cash flow and everything. So if we have to talk about specifics of investing, let's start with equity. So, you know, the COVID-19 like crisis send shockwaves around stock market back in March. BSc, Sensex fell to about 28,000 points and though it has gained some 10,000 points since but the markets still remain highly volatile. So, Rahul, what are guiding to you should be the investing strategy of equity investors in volatile markets? So for me, when I look at investing strategy, I look at equity or other classes separately, I look at it the holistic way. For me, BSc is one of the ways which has been working whether it's a bull market or whether it's a bear market. And asset allocation is what it's about understanding investment objective, risk appetite and investment horizon. And then you get a good portfolio which is a mix of debt, equity and gold all across. So I think depending on the on your risk appetite, your investment horizon, what age you are, you can have a good asset allocation ratio. And then depending on whether you're in a bull market or bear market effectively, you can realign your equity portfolio accordingly. We always believe that you should ensure booking your profits in equity regularly and also when the downturn is there, you should use this opportunity. The best part of asset allocation which I feel is that it takes out the emotion of investing. I think it rationalizes one risk to the behavior which is otherwise guided by mostly greed and fear. We have often seen people blind to risk and bull markets and blind to opportunities in a bear market. Asset allocation as such in that sense helps you in achieving on both the sides. So asset allocation of the strategy works well. Yeah, completely true. But you know, so I was just reading some reports and I was reading amphidata also. So what I saw was that you know, in the beginning in March and April, the MF inflows were not so much impacted SIP especially, but later in, in May, June, the inflows came down. Maybe it had to do with salary cuts or, you know, we can't know what the reasons were, but it did happen.  In fact, wait for the market to correct. And then if you have to exit, then you wait for it to start rebounding again. But the general investor behavior is to exit when the market is falling. And we have seen that this time also it was no exception. You know, another trend which I have seen is I was also reading some report by Zerodab that a lot of young investors I have started flocking to direct stock trading during this pandemic. So on one hand we see MF inflows going down but on the other hand we are seeing, you know, a spike in investor interest in stock trading. So how do you see it? How do you see this trend among young investors? How, how, you know, safe or how do you see it basically? I think very relevant question. So both points of yours. I think you answered it yourself. I think SIP is a good, safe way. And I think Rahul made a much relevant point on the overall concept of asset allocation. And I would seriously urge all the listeners to actually give a lot of credibility to what he said because it's not a question of equity and debt. It's always a question of your overall asset allocation. Drilling it down specifically to equity. You made a point and point that SIPs have a lot of value because if you continue with the journey of SIPs over a long period of time, you would have seen markets at high levels, low levels and it sort of had this whole tendency to average it out. And I think all of us have always heard, listened, but never unfortunately fully implemented that the real reward of investing in equity markets is over long periods of time. There is a power of compounding and there is a simple rule of 72 that many of us follow. All that the rule of 72 says is 72 divided by the percentage of returns that you get is the number of years it takes for your money to double. For example, if you believe that you will get 12% rate of return, 72 divided by 12 is six years, your money will double. Now, and usually you can anyone can check this factual data Indian markets over the last 10 years is in the region of 1112%, which means all of us know that if we just stick to that philosophy do not get swayed by what is happening right now because these markets are much more resilient than one year going here or one year going there. And if we continue our journey through the mode of SIP, then 11% 12% from a growing economy like India is not too difficult to expect. And if that be true, we are looking at six years seven years for the compounding benefit to really look at your money sort of doubling it's pure mathematics. It's not any advice that I'm giving on your point of stock trading. Yes, I think with all that is happening in the market. Because of players like zero that you mentioned, there has been a lot of technological disruption, which is giving the new millennials the new professionals ability to trade on a very seamless and a friction free on platforms such as zero and many others, and also on very low cost. And I think it's a brilliant thing because it is leading to democratization of investors who have always been very very of entering into stock markets didn't know who to call how to call and there was always that inertia. And also there was an expensive that now feel more comfortable, just onboarding themselves onto a platform, which is done in a very user friendly manner, very cost effective. And they feel that they could using that platform start buying some stocks or to that extent the story is absolutely apt. But my very strong word of caution is that stock market, unfortunately, is not all art. It is also science. There is a reason why certain stocks do well and there is a reason why certain stocks do badly. And there is a reason why there are so many professionals who are employed in the area of equity research and management and mutual fund that each of these stocks, ultimately behave in the way the underlying companies are set to behave. So my limited word of caution and advice to all my fellow listeners is it is absolutely brilliant that they are able to get platforms and they feel much more comfortable buying and selling stocks, but they should very clearly decide. Are they in this for the purposes of trading and making quick money, or are they in this as long as creators, if they are in this for the former. Well, there is very limited value that I can do because then there is not much that you can do with research or science, you get lucky you don't get lucky you win some you lose some. But as far as long term creation is concerned, if they are going to these platforms and, and both advice and could also are offering these kind of platforms to investors. I think they should do the second part of it also right. Not only should they invest in stocks, but I think they should, they are well advised to read about the companies that they are buying if not do in depth research, a little bit of what the companies into how the, what level of cash flow the company has, what is the profitability of the company, what kind of revenue growth the company has, how much the debt as the company has. It may look too technical, but trust me, if you do that over six months to one year, just have about five or six parameters that you look at in about six months time you will get a hang of how to look at companies, which you think will not be into any big risks and big volatility. So my limited point, it's a great healthy trend, but it should be alongside with exercising a lot of caution should not be done only for trading purposes should be done to create wealth over long periods of time. So on that note, what you just said about the fundamentals of stock investing, we have a question from one of our readers was asking, sorry viewers was asking that our pharma and stocks and attract proposition for the next one to two years. Anything you would like to suggest this viewers Shrikanth on pharma and it stocks, whether they are an attractive proposition for the next five to six months. Both of them are done exceedingly well. So pharma stocks are almost close to the 52 week high some of the ID stocks are doing exceptionally well. I would refrain from giving too much of a sector view because our own view as of now is, COVID has been such an unknown unknown that taking a sector bet in an ecosystem like this, it can have multiple ramifications. I think what we are dealing with right now is very limited transparent information. So I think what the view of our own form is to why do not ditch overall equity as an investment class, but do not go too much as far as sector bias is concerned. So I will have to stick to the view that our own view is we are not being too bullish or bearish about any sector. We are looking at it as a slightly more diversified call, but any investor looking at pharma, which intuitively looks like it's going to be a great bet because of all that has happened in general consciousness of investors over healthcare and pharma post COVID. Similarly, the entire disruption that technology builds is giving way to a narrative that it stocks will do well is okay to the extent that the overall philosophy that I mentioned is there. But one look at the stocks also seem to suggest that they seem to be very well valued. I will not say overvalued or undervalued, but they are very well valued. So investors should exercise caution. There are certain mid-cap pharma and IT companies that we at least believe that are looking very frothy. The leaders of course will always continue to do well. So again, two things. Both these sectors intuitively look like good sectors to hold. The leaders in these two sectors should continue to do well, but the mid-cap stocks in these two sectors are looking a little frothy. But from our point of view, we are right now not making too much of a guessing game. As far as sectoral picks are concerned, we are advising investors to stick with a slightly more multi-cap diversified sort of an approach. So I have one more question on the six-year theory that you were just talking about, Srikanth. So I'll quickly take this question up since we just spoke about it. So Rithu is asking, with the six-year theory, what should the portfolio look like and what are the best practices to be followed during these six years to reach the compound return goal? So the golden rule is not to deviate. I mean, the six years, give it six years. Unfortunately, we all talk of six years and in six months' time we start debating whether we did the right thing or not. I think honestly, trust me, there is no shortcut to doing this. You have to go through this period of cycle. There will be areas such as global financial crisis of 2008. There will be areas such as COVID-19. They will come. They will go. But you stick on with it. There would be good periods where the six will get crunched to five, where the six will get expanded to seven. But by and large, if all of us are eternal optimists and we believe that human endurance is strong enough for us to bounce back and this is not an apocalyptic situation, we should not hold our, we should not lose our patience and continue. So the first, do's and don'ts, do not deviate. What do you think? Walk the talk. Second, I think don't be over-cute as far as sector teams' talks are concerned. If you general and the return that I gave an example was of simple nifty. So you don't really have to even go to nitpicking with stock, which manager beyond the point. If you like a good fund house, there are fund houses like HDFC, Kotak, ICIC who are amongst the top three, four, five fund houses and have been there doing businesses for a very long time. If you just pick a good fund house, diversified multi-cap strategy, I think you are good enough. I think there will be periods of time where this is your own advice. You can dabble a little bit into research stocks, into small-cap mid-cap areas, but I think if you just choose good quality mutual fund houses, good quality ETFs, stick to the larger diversified theory and stick to the six-year, seven-year, eight-year plan, I think there is nothing that can stop you from building a little nest egg for you as the time is, and I will again urge all leaders not to hold for the six-year point of view very strongly. The mathematical point is 72 divided by whatever return you get is the return, is the number of years that it takes for you to double your money. It's mathematics, so for example, the next three years, Indian markets give you 24%, then in three years, the money doubles because 72 divided by 24 is three. If Indian markets gives you only 7.2% return, then it will take you 10 years because it is 72 divided by 7.2, it's 10 years. Historically, in the last 10 years, markets have given close to 11-12%, so if I use that yardstick in your cycle for people to develop that over a period of time. Absolutely. Okay, so we'll go back to the discussion and keep our questions on hold for a while, but before I do that, I have a word for our Facebook viewers that you can ask your questions in the comments section. We will make sure that they are all answered at the end of the discussion. Okay, so moving on, Raul, let me come to you.  So, so, you know, for risk-averse investors, debt options are also not looking too attractive because there have been massive cut in interest rates by the RBI. So, Raul, what should bond and fixed income investors do now? So, if you see in the current scenario, I think creating a debt investment strategy, especially what you said in a falling interest rate, I think it's not the biggest challenge in the social system. For example, now ISIS, the bank is giving up more than a year every 5% which is fairly, fairly limited. I think it's a complex situation because the investors choose between safety and return. So, if they settle for a safety of bank or quality, I think they lose out on returns and if they aim for higher returns to a corporate deposit or something else in NCD format, then they are little compromising on credit quality. I think one of the options is that the debt funds gives you an option of playing in the falling interest rate market, but I think that is something who understands that funds should dabble into it. As a strategy, if you look right now, we are looking at diversifying the whole debt portfolio into various parts and there are interesting options available there in that sense also. So, for example, you can have a combination of FD, then you can have triple A rated NCDs which are would be around 7 or 4%. You can look at an option like an RBI bank which just closed with an almost amount of info which happened a month back at 7.75, which was again a very attractive rate at looking at the quality of credit, what is debt? So, I think a composite of FD, RBI bond, a government tax saving bonds and then triple A rated and some you can have double A plus which is percievely high risk but reality is high quality credit. Then you can have a good combination of diversified portfolio and still make a good optimum return around 7.5 sorts. So, that is how we are suggesting to our clients or investors who are primarily looking at fixed income instruments and I want to then for them safety is the utmost important criteria. For them, we are telling them have this composite sort of portfolio and just don't put everything into bank FD. So, putting an RBI bond at 7.75 or put in an ICC bank FD for me is reasonably the same thing, correct, effectively. And then you end up making more money. Yeah, there might be some terms where you have a higher lock in on RBI bonds but effectively most of the FD users just keep FD and they keep rolling it over. And since you have a diversified portfolio, a certain part of portfolio can anyways be liquidated if you have some exceedances coming in. So, that is how we are suggesting and helping our clients and investors how to dabble with such a situation where their interest rates are falling. But I tell you, it's a big problem. It's a big problem for more of senior citizens because they generally are dependent on cash flows from FDs or the things they deposit etc. To manage their money. Yeah, definitely. People have also reduced all this is impacting but effectively now you have to dabble between safety or returns and in this environment it's better to be safe right now. Yes, definitely. So, I also have an add on question here and also coming back to the whole point of what we were talking about assessing your financial risk. So, do you think that volatile markets as well as the coronavirus economy presents a good opportunity to reassess your overall financial risk because if seeing a downturn people are moving out of the market equity investments, it fundamentally means that you really can't take the volatility that comes with equity investments. So, do you think it's a good opportunity to reassess your financial risk? Yeah, 100%. So, for example, if you see your assessment of financial risk, other risk you can take are two parameters I spoke earlier also. One is willingness to take risk and the other is ability to take risk. Ability is generally derived from your job security, your current net worth, whether you have dependent parents, children dependent on you, how the family structure is. And the other is the willingness. Willingness is more of your perception, your attitude, how you're bringing has been, are you have been conservative as an individual and all of your risk assessment tools, etc. are there. But the real, the way you react comes into the real situation. Anyone, any single individual does not like loss in his, whether it's temporary or not. And so he does generally don't like losses, correct, in the portfolio. I think the situation like this in current pandemic, it gives you a good heads up of understanding that what type of risk profile you really belong to. Because if you see in the whole movement of market from March to now, it went to 7500, now it's back to in the summer 200, 40% uprise. Effectively, there are a lot of people who squared up because of risk and now also are having a FOMO, fear of missing out in their thing. But the fact is that you have to have a clear understanding that what is the risk profile assessment, whether you can take that losses in the volatile times or not, because that is very, very important. And that is a good thing to learn about your future investing. That is one. I think the ability to take risk also changing, which I spoke earlier, if your job is under threat, you're having a salary cut. I'm sure the network, if it's an equity, it was also got significantly downgraded in terms of portfolio size.   So that you're able to achieve your financial goals in long term. Yes, of course. So we have about 10 minutes left. So we'll move on to questions from our attendees. So I would request our team to please give Mike to Ashlish. He has a very interesting question. Hello, Ashlish. Ashlish, please unmute your mic. Okay, so there's some problems. So I'll ask on behalf of Ashlish, his question is, what would you suggest during this crisis, SIP or lump sum? So who would like to take this question? Since Srikanth has given the 72 formula, I think you should answer. I think SIP is a much safer bet. It will be always a safer bet, not only in this environment, but in any environment, because the question is from a market timing point of view, SIP will always win hand over fist. Lump sum you do when you have been faced with an inordinate amount of liquidity and you are okay investing it over long periods of time. But 99 out of 100 times, it's always best to stagger it, especially in an environment like this, when the markets from A went down to B and then back to A. Situations like these to navigate these tough waters, it's always a better idea to stick to SIPs. So there's a question from a, this person looks like a stock trader. So he's asking, would you say volatile markets are the best avenues for trading and why should it be always long term investing when it comes to stock trading? I mentioned that there is absolutely no right or wrong. You should know your temperament and there are investors. I mean, it's not that people don't make living out of trading. It's a very big profession, but you should know the nuances of trading. My advice is to all other listeners who are looking at investing as a philosophy for either creating wealth or preserving wealth. Trading comes with different sets of nuances. You need to have the ability to buy, sell, have the temperament to take losses, have the ability to read charts. So as long as you are able to do that and you enjoy doing that great volatility again cuts both ways. Volatility does not just mean down, volatility can mean both up and down. So volatility can be a friend as long as you know how to navigate through volatility, but overall volatility is, I mean, I would always do well without a volatile situation, something which is slightly more scientific and predictable, even for a trading sort of an approach works very well. So it's not that whether volatility is good or bad. It is just that whether we have what it takes to navigate volatility, we have what it takes to navigate the nuances of short term investing and trading. So I'll clarify. There is nothing called right or wrong. Investors looking at creating capital, preserving capital are better off, better off approaching it through the fundamental ways of investing. Investors who like the area of finance, who like, who have the ability and time and bandwidth and wherewithal to understand charts and have the risk temperament to take positions on both sides can obviously trade and that's a big community of investors who also make a lot of money doing that. All right. So next question is from Priya Dashne. She's asking, my father is retiring in March 2022. His portfolio fell significantly in the recent market crash. Should he exit or wait for it to recover? Rahul, why don't you answer that? Sorry, can you just repeat the question? So she's saying that my father is retiring in March 2022. His portfolio fell significantly in the recent market crash. Should he exit or should he wait for it to recover? So I think if it would have fallen in the recent crash, I'm sure it would have come back also because market has also improved significantly in the last couple of months. That is one. I want to come back to the, again, the same point is that at his father's age, I think the asset allocation formula would be 100 minus your age. It could be an equity portfolio. And if your equity portfolio is more than that, it could be converted into debt. And for a person who is retiring, our advice is that a large part of the portfolio should be into debt. If you have good recurring cash flows on monthly basis, that ability to meet is expensive, D2D nature is really possible. So in that sense, if the asset allocation percentage of equity is very high, it should be reduced and it should be largely debt. That is how it should be considered. I think right now when the market is again come back to 11,300 levels, it's a good opportunity to get out of equity and convert into debt. But it will be a good, in that sense, a good opportunity to get into the right asset allocation. So a sort of an add-on question here we have from another viewer. So once she's asking, this is interesting, is there a chance of markets revisiting the March 2020 lows? I think it's very difficult to predict what will happen in the market. But seeing the current parameters, how the FIF lows, how the results are coming in, et cetera, the market does not seem to go back to 7,500. That is what our view is. But market has been very unpredictable. It has always been unpredictable. It will always create fear in you. So that is surely a guess to take. Ishegan, anything you would like to add here? If you would like to address his concerns about whether the markets will go down to its March 2020 lows again? If I could answer that with certainty, I would be in a different trade of business. But yes, I think it's a fair question because since you very recently saw 7,600 levels, the mind always thinks that what can trigger that. I think I would tend to agree with Rahul. I think while you don't rule out anything in the markets at all, because you don't know what the next cannonball to hit you will be. But it looks unlikely. A couple of reasons. I think the world has digested the issue of COVID. If you look at two markets, both US and Japan. US contracted about 99.5%. Japan contracted about 7.5%. These are big numbers for economies of the size of US and Japan. Despite that, markets did not fall. Japan, in fact, after giving the data of GDP growth of minus 7.5%, only fell down by 0.8%. Similarly, US, the day it was down by 10% GDP was marginally down. So I think the bad news is somewhere being factored in. All the central banks across the globe continue to keep the tap open as far as liquidity is concerned. And I think even in India, with investors on the SIP route and also on the FBI money coming in, I would put the probability very low of market revisiting that kind of a situation. But I won't rule out a correction, but I will not give a very high probability of a correction of that magnitude. Right. Okay, so I'll take one last question. Rahul, maybe you can answer this. Our reader is asking, sorry, our viewer is asking, how do you define the word long term and what are the indicators we have to look over when we're saying long term investing? So long term journey in equity market is three years and above and she can't can also add to this. Three years and above is what we look at long term. I think the parameters of long term which we want to look is what she also spoke about that you have to maintain that discipline of continuing this investment. For example, if the SIP is there and the formula of if you think it's grow by 12% and will go in six years, then you have to continue with that discipline. That's an important parameter of long term and and and from equity standpoint of you, I think three or plus something which you should look at long term. All right. Okay, thank you very much Rahul and Srikanth for joining us today for this really engaging conversation on investments and you know what investors can do right now during these turbulent times. So, well, we hope to have you again for another interesting conversation and thank you viewers for joining us today and well have a good day ahead. Thank you very much. Thank you. Thank you.


Yeah it's been amazing, really good weekend, a little bit close to the edge. We used to do hill climbs with them, we were both drive, so yeah this is the longest thing I've done, it's only okay, so first stage being 30km was a bit like, whoa, but it's been really good. The first one's very tense, you know. I didn't really know what to expect, but it's been so good, it's just gone so fast, it's been so good. Paradise Valley Road was pretty awesome, as the shortest climb was only 7km, but so many spectators and things. Pretty awesome, seeing people out there and cheering you on and things. You know, like with family and it's like we've got to come home, you know. Yeah we had to respect that and I think we drove it hard and still tried to play safe. Yeah, I'd love to have my own car on the Tiger one day, be awesome.


Hello, and welcome back to the craft box. My name is Brent and today We are back on pirate 101 for a companion showcase today.  He's the first Buccaneer that we're doing on this series. He what is this? I don't even know what half of these are. I never used some like actually never use Never use rat beard. He's a buccaneer He has three promotions, so yeet, and he gets quite a few epic not epics Yeah, I think they are actually kind of no, I don't know whatever they're called the powers So yeet Let's see.  They're all going for old scratch. She better not die. That would be embarrassing That'd be really embarrassing. I mean I could hit them, but I'm gonna do that Look at this. What is this? We're gonna go like that sure I'm just gonna do that and we're gonna do that just to just to do that because we can Um So yeah, he's he's acquired after the volcano dungeon in Skull Island Look at that. That was kind of cool But kind of cool. I mean really cool back. That's actually super cool Okay He's a quite after the volcano dungeon. He's actually the antagonist Um For most of the first part of the story so Yeah, I mean like that's rapid for you Somehow we recruit him and stuff happens. So yeah What else we just go so slow relentless stop it. Stop it. Stop it.           That's the last time I'm hitting geez I'm just gonna heal everyone. I think that might be the best idea Okay, we are going to heal everyone Fine, we're going to heal myself so a super strike looks a bit Like Epic here a Bit like this But but but he goes like 360 spin. It's quite cool. It's actually really cool So yeah, that's a super strike and I'll show you his um other one Unless he kills Ripple scratch Maybe not okay. I'll show you his other one now Um, we still don't have a heal So this is his buccaneer smash. I think it has Unlimited range, so like just wherever that's actually really cool. Oh my I should use rep bit a bit more often I think he's actually really good companion Anyway, I'm going to end off this video here So, thank you for watching remember to leave a like and subscribe and if you've already subscribed Chris we love about you know exactly when each episode comes and remember craft outside the box


President, I'm keeping your company on around the North West. Now, history has been made with the historic Donegal steam engine, Grumvold, installed at the Donegal Railway Heritage Museum in Donegal town. And it's quite a milestone for not just the museum but for the county, because this is the first original Donegal steam engine returned to the county in many decades. And the manager there, Adam McCauhey, now joins us for streaming as well on YouTube and Facebook. Now, good afternoon to you. Good afternoon, John, right over here. This is an historic engine in a number of different ways. But in particular, this was the last train to run here in Donegal. Is that correct? Yes, it was. Actually, Drombo was the very last engine in the 31st of December 1959. The very last train left was Drombo from Donegal town station here to go through Stronholder and they end up in Stravan. And that was the very last official steam train to run. There was some trains running in January, but that was more lifted than laying and that sort of thing anyway. But this engine is quite an historic one. And to have that engine back here on site, particularly is gratifying for us just to have it back here. There wouldn't have been much of a fanfare with there at the time. It was in a case where it just sort of faded out. Now, there was a lot of fuss when it arrived back here. It was at the tail end of last year, which was great. But when it was leaving, when it was sort of exiting for the last time, would there have been much of a fuss back then? I think people were shocked to hear that the whole, I mean, from looking at the newspaper articles and talking to people, I think people just thought it was a terrible decision. And this decision, of course, wasn't made locally. It was made further in Dublin. And there's always been this being, I suppose, Donegal, but not in the sixth stat. It has, there's been underinvestment. And this was at the time seen as another near the coffin in relation to investment in the Northwest and had a massive impact. And in fact, I think people were very emotional to a way of photographs of people at the send off here at Donegal Town and then at Sturban and whatever. And people were really shocked. And because it was, you know, it was used for everybody, not only for tourists, but for going to school, for commerce, for just getting about January. And it went all over Donegal. And of course, at that time, the government promised that they were going to install a lot of new infrastructure and new roads.  And I think people were very emotional about it at the time. And the one thing, John, we were surprised at was whenever we took the train back quickly on its return journey on a low loader and took it back to station, the more older people coming out who are very emotional about it saying that they never thought they'd actually see an original Donegal steam engine back here on site. And I have to say it was kind of taken back a bit by it. And we have people in tears, whatever I'm saying, they never, never thought they see a big red steam engine here back on site. So I have to say it's just been great. And we do have lots of people who come in and we had our official opening last week. And that was the same thing as people just were delighted to see the return of the original steam engine from the county. So those older people that you refer would have remembered the railway when it was here in Donegal, and now that there's an original train back, they're delighted and it's a bit of a surprise. It is. And we're getting people coming from near and far. There was a lot of coverage at the time, both locally and nationally, and also internationally in relation to the Donegal Railways. I've said John before, where you're looking at, Nick, it was the largest narrow gauge on these islands, plus also the Donegal network was one of the first, globally one of the first networks to have a combustion engine. That was a non-steam engine on tracks. And that's amazing. When I heard that fact, I kind of went, are you right? And that's what it was, you know, whatever. So it's quite famous globally, but it's only now that I suppose we're kind of, really tourism has taken off massively in Europe and further field, but it's only now that there's a major opportunity to develop this further. This museum has been here for a number of years, but it had to go through kind of a change where the last few years kind of bring it up to date. And that's what we have done. And Drombo is certainly the showpiece, but you might have remembered, too, in the last few weeks we got installed. I got funding through the Heritage Council and we got funding to install Ireland's first interactive steam cab. And that's for kids and adults, and it gives the sensation, but also it's an educational tune. And that was important because we wanted really to have something for younger ones and also older ones, but also something to give people the sensation of traveling in the steam train. But in relation to Drombo was particularly leader through DLCV that brought funding in. And then also Henry Forbes, who introduced the combustion engine, his grandson Graham made the donation, and that kind of got the ball rolling. And then with public funding and different things, it was great to make that happen and at it. And the same time, too, last week at the opening, it was part of a journey for us, but the journey hasn't stopped and we actually do have a phase two. The phase two is actually more ambitious and that is to run some Donegal stock near Donegal Town. So the next thing we're going to look at is doing a getting funding to do a feasibility survey, to look at options and look at locations and we're quite serious about it. But I thought that we needed to get the first phase to get a steam engine back on site to get people to come and say, God, we're serious about this and people keep asking about wouldn't it be great to have either a steam engine or a real car running locally to the town somewhere? So it's something that we pitched the politicians last week and we're now, I suppose, getting people talking about to take it on to the next phase. So if it was to happen, would it be Drombo? Possibly, but this Drombo actually has been restored more or less operational order than the entire train. The only bit that hasn't been restored is the boiler because whenever you restore the boiler, you get a 10-year certificate, it has the pressure test and that counts down as soon as you get it. And to get that certificate costs about 100,000. So what we will do is whenever, if we do, if Drombo does go into steam and it could go back into steam, then we would return a steam engine up just to get that boiler started. But that's an option. Drombo is an obvious thing, but also possibly a real car too. I have been talking to people about data, about the possibility of running a real car or something else or another bit of narrow gauge and there are lots of options and locations where I would love to run it. There's lots of suggestions, of course, but you have to work around funding and then timelines and farming and farmers and different things. So it's being considered. Yeah, it is considered at the moment and now, I said, people are returning to the museum here and I think a lot of people are shocked and really surprised about the transformation. I mean, really, it's now, I mean, I was talking to somebody this morning about saying, look, it's now become one of the wee hidden gems in Donegal, but it's actually, we're getting great reviews on Google and TripAdvisor, superb reviews continually now and they're actually coming to one of the musty if you're coming to Donegal town, like we're open nearly 365 days a year and you know, and we cater now for all age groups and just because of the new drumbo, the interactive signage, the new interpretive signage and also we've got a ride on rail which for kids is a smaller thing which are run during the summer and other things and just now people certainly are certainly coming back and visiting R2 and of course people if they're interested, we're only 300 meters or 300 feet from the town centre from the Diamond, only just below Donegal castle, quite easy to get to and open now the moment to Saturday most days and then after September, open six days a week, but as I said, people seemed to enjoy it and our staff are very good too, because they're an important part of it too, you can get around and chat to them and lots of people are coming back, both locals and also visitors to international. It's only a hop and a skip from the Diamond on foot and it's great, it's great for railway heritage and it's also great for Donegal town and there's, I mean, you wouldn't be getting all those positive reviews if there wasn't plenty to see and do there. I know there is and I said that's deliberately we've done that because a few years ago I would have been geared towards maybe older people and we decided really particularly to focus on families too, so we've a lot of software families to keep it entertained, we've got weed quizzes for kids, we've got the interact or receive cab, we've got a rail and other bits and pieces more than all to use it, really trying to keep it for everybody, but also tell that unique story and I have to say, John, it's for the entire county, it's not simply the County Donegal, we also do a lot on the Swilly and we brought out earlier this year a new book about the Swilly and we've done, so we're covering the entire the Swilly, the County Donegal and also the DNR and in fact this year's badge, which we've just we do a badge each year and this year is actually a swilly engine, I was looking to see if I had one to show you, but some of the day we have a, people can see a wee swilly engine there, green one, so we do, so we do one each year or whatever you know, so it's for the entire and it was you know from County Donut down to Petticole to Killie Beggs right across to Sir Norder and then of course into Sturban and Sir North, a wee bit to get me in there. You're even involved in the food festival this weekend, what's what's happening there? Well we're doing something a bit different, it's always one of my ambitions that we try and use these way of unique spaces here that are available for hire and we've had meetings, a group season, and for training and meetings and one thing another, but I always thought it would be great if we could do something like an Orient Express high dinner thing, so I would talk to the Chamber, actually your two go over this and others, but Mary from the Chamber contacted me to say they'd actually love to do it, so they're actually that's on tomorrow night and it's going to be done up, the carriage is going to be decorated like it would have been a high class Orient Express. It is, I wanted to express and I have to say they've got a fantastic food menu and I think what really surprised the Chamber who are doing great work with it, they've got a great range of events over the weekends who go on and check on their website and Facebook, but they advertise it not sure on how it would go and it's sold out within three hours, I mean phenomenal. I want to think so, you know that's what we want to do, John is just unusual to have unusual events here, and I think that's an obvious one, people and we're getting some people are dressing up and there's going to be singing outside or whatever, so sadly there's no tickets available, but maybe the next time they do it we might do they might do more than one night or whatever, you know. It's great and I can see why it's captured the imagination, something a bit different. Well there's some continuous success over there at the Donegal Railway Heritage Museum and keep in touch and as the development along the way, no doubt it will be in touch. Thanks now. Well thank you for that, bye bye.


yeah thanks a lot for showing up sorry I'm I have a slight cold so I'm highly doped but yeah please bear with me I totally want to give this talk and I'm really happy that so many of you are coming for such a boring topic documentation is boring right no okay okay you're always already one step ahead of me so quick survey how many of you are involved in open source projects okay how many of you are open so involved in open source projects that don't have any documentation how many of you are trying to change that and how many of you have actually written documentation before whoa whoa didn't expect that okay so this talk is titled writing open source documentation for open source project it's based on our experiences at SUSE but we can apply the lessons that we have learned to other projects as well and I will tell you how to do so first something about me my name is Christoph Wicker as you have already heard I'm a Linux user since 1999 in 2005 I became a contributor to various projects such as the Fedora project where I've been very active if people know me they probably know me from Fedora also I've been involved with XFCE and the LXDE and the one laptop for child initiative in 2010 I was hired by Colab Systems the nice guys downstairs with the Colab Cooper server and yeah early last year I joined SUSE as a technical documentation writer and as you can see here I'm not sure if you can read it this is the invoice from the first ever Linux distribution I bought SUSE Linux 6.1 student version for 79 Deutschmarks in 1999 one of the reasons why I purchased SUSE was well everybody was using it at the time if people were using Linux they were using or in Germany in particular they were using SUSE and one of the reasons for that is it was a German distribution and it was always very strong when it comes to documentation so documentation this big handbook was a great benefit I still use this even when I no longer used open SUSE I've been using other distributions I've been using Debianfit or whatnot but still documentation was the key so that's me who are we that's the open SUSE documentation team at the write the doc doc's conference in Prague in fall last year I think they can see me down there in the back you can see our team lead Marcus Finer probably some of him know him from Linux magazine and yeah that's not even all of us there's more because we have been growing rapidly SUSE has been growing the documentation team has been growing and also the numbers of the number of products that we are to document is also steadily increasing so who are we so the next question obviously is what do we want and we want to document all the things so much for the laughter that's that's the only picture I suck at slides so the rest of this presentation will be boring yeah what do you what do you mean with document all the things here's yeah you probably cannot read it I can't read it either it's too small here you have an overview of the SUSE documentation website as you can see it's quite a lot if you go that's only by products if you go further down into one of the products you see are different kinds of guides like get it started or quick install guides deployment guides user guides administrator guides then certain topic oriented guides like tuning guides virtualization guides and of course with every new release we have release notes all of that sums up to I think at the moment it's 14,000 pages if I'm not mistaken with SUSE Linux Enterprise 12 so that's quite a lot of documentation and the question becomes how do we handle that how do we write it and how do we handle it so we are talking about the tool chain SUSE has basically written a tool chain of its own because we figured at the time we started I mean that predates me joining SUSE but at the time they started they couldn't find any decent tools if you go to if some of you are in documentation and they go to special documentation conferences not like write the docs which is focusing on free software but to like take home the German documentation foundation for technical documentation you will see all of that is proprietary and of course SUSE didn't want to go that way so we did everything on our own and we wrote a fully complied open source tool chain we start off with dog book XML for us it's the language of our choice I know there are others I know that that actually we are like the dinosaur everybody has moved on to something more modern like like just markup or yeah there's there's plenty of stuff but at write the docs I figured that we are one of the few to use doc book but on the other hand I very much like the semantics well there's there's a lot of advantages too much to explain it now I could go on but we really figured it was the only language that catered all our use cases whatever other language came up there was always some feature missing as it's dog book as it's XML it's as people say write only language you can write it but you cannot read it right the the upside is many people are familiar with HTML or XML in general and many of them can you can learn it pretty quickly if you just do a short if you want to submit a short patch or something like that you can if you see para para okay that's probably means paragraph I should put my text into inside a paragraph and you're done so that's pretty pretty trivial and you can see all about doc book doc book dot org next when you have the language you need an editor you know probably know this from classical programmer paintings on tumblr that is the everlasting battle of e-max versus vim so yes you can use any editor you want I'm favoring vim most of the others in the team are using e-max there are proprietary editors there are you can use G edit J edit whatever atomic you know it atom yeah atom so many of them once you've created your code in or your dog book files in the editor you need to somehow publish it and this is where our toolchain kicks in we wrote a tool that is called dubs the dog book dog book authoring and publishing suit this is on github it's open source you can use it so some people say well what is dubs it's basically a rapper around make and I hear some of you complaining oh are you really talking about new make I hate new make no actually new make is the I mean it's the dependency based build tool and that's exactly what you need if you want to generate output files when people say they don't like make it turns out they most of the time they are using they are talking about auto make so they are in fact referring to the auto tools which I don't like either but anyway new make is the tool of our choice it's running in the background and you have one front and which you can use to do all kinds of commands the simplest thing is dubs validate you want to know if your output is valid if you want to generate a PDF file you just type dubs PDF you can see that make is running in the back because the that's actually like the targets for make PDF HTML then you can also pass options like gray scale PDF or HTML single otherwise you get a chunk of files we have lots of formats you can generate man pages plain text files plain text files are not that easy we are using we 3M the browser when it comes to tables you want to have a clear output so that's why we first render it into HTML then use the browser to display it and save it to a text file you can do it up with calibre and from that you can also generate Moby files for your kindle and you can generate the web help that's a special format of HTML it comes with a with a table of contents at the site and with a search bar that is using some JavaScript so if you are using for something standalone for your product and you only want this one single help piece on the internet you probably go for web help but you can not only generate output formats you can also do lots of interesting stuff with it okay here I need to explain something there's a call the minus D parameter refers to the configuration file every document has a configuration file where you specify the document route the starting point every XML element has an XML ID so you start as say from here on I start so you give it the configuration file and then you can say list files I'm looking for the in I have a ton of files in my repository and I'm looking for the file that contains the root ID art for article dubs quick and I can get that without I mean I could get that with grep probably but that would also list of a lot of false positives so we have a command for that or you can give a say generate me a list of all images with the modification date and also show these images in a viewer so it's quite quite a comprehensive tool then we have some SUSE specific commands dubs lock drop so the translation we do we are it's written in English even though most of our team is German which sometimes you can really see it was written by Germans because Germans have a special way of writing or speaking English especially when it comes to the to the words like have to must need their use differently in German and yeah so we write in English and it's then generally translated by translation agency by an external translation agency that's focused on technical documentation in order to have them translate our software we give them basically a big table in a clearly defined format with all the images and so on so that's generated with lock drop and after the translated documents come back we can do unpack lock drop or we can just do the online target dubs online to generate online doc to generate the online documentation that you see on the SUSE website so that's actually a quite powerful tool we are still improving it and we are meanwhile not the only ones that are using it while back we received our first patch by somebody from salando you probably know them so they are obviously using it too next in the tool chain we have the style sheets you have the XML and you need a style sheet to generate the different output formats for example we have standalone books or bigger like the manuals the guides we have single articles which are just a few pages we have just just the HTML and we have different I mean it's the difference if you have a PDF or if you have a website for example on the in the PDF file you want URLs in links to be written out because on paper you cannot click I mean you need to have them written out so this is done with the XSLT style sheets yeah the next we have a style guide that reminds us how to phrase it's not only about phrasing it's well how to spell certain terms recurring terms what tone to use how do you address the reader what's the target audience and all of that so you want to have a consistent voice throughout all your document you want to have consistent namings consistent use of terms and all that's and also the structure and markup needs to be consistently all that's in our style guide we then have a style checker which is a tool that you can manually run on the on an XML file it will output of an HTML file which you can then view in the browser and if you view it in the browser you get this nice these are actually little plus signs where you can just fold the the paragraphs and then you get a list of well notes and warnings of things you should probably fix so much for the style checker we have yet more tools all of them are on github in the open SUSE organization dubs and is something that we just finished recently or it's well it's not finished but we brought it into production this week it's continuous integration with Docker we have dbx included for well in any of you knows doc book you can have includes but you have the problem that if you have XML IDs they need to be unique and if you use an include various time and document the the IDs are no longer unique that's something that we solve with dbx included we have a doc manager that manages meta tags for example is this document going to be translated or not that's something or what path is once it's published on the website what's the URL these are custom tags that we added and they are managed through the doc manager we have a doc stats tool gico doc is our dog books subset we don't use the full set of dog book because it's just way too big we want to actually limit the documentation writer to a certain subset of elements that they can use and also that that allows you to enforce guidelines like you must not use nested lists with x level of nesting or you must not use this element inside the other element and all that's in the gico doc of course you need an editor that can read the schema files and that I mean that not only does syntax like syntax highlighting or autocomplete but that also like the the structure of the semantic syntax thing and also XML diff and G next and G is next generation there was already an XML diff out there if you compare XML files the classical way as you do with git for example I mean even though we try to have very strict with with the dimension dubs auto format earlier so we have common formatting like like indentions and and no white spaces at the end of the line and all that even though sometimes patches look messy and that's why you can use duck duck the XML diff and G to really compare the content of the files not the XML syntax okay so much for the tool chain you can ask questions later now I'm going to talk about the process as I say it's all open everything is on github here you see the doc sly repository so that's the it's no longer the open SUSE organization it's the SUSE organization on github you have doc sly and other repositories all prefixed with doc that's us Sly is SUSE Linux enterprise server and related products here you can see the DC files for the admin guide or for the everything guide and so on yeah it's on github you can submit pull requests you can you can take it as you need it and from the Sly documentation we also build the open SUSE documentation it's basically the same thing except that phrases like SUSE Linux enterprise are replaced with oh the time is actually getting longer oh I was hurrying up and and so now I I have 30 minutes left okay I slow down a bit thanks yeah it's on github you can use it you can fork it you can do whatever you want with it you can even some people even we were surprised a while ago when we saw our documentation on Amazon somebody is obviously generating books from it printing it and selling it we have no idea who it is we have nothing to do with it but it's our documentation it's it's really ours we verify it so you can do that it's open it's all gftl licensed use it as you like so when we are talking about git I need to explain the branching model a bit maybe some of you have read this article the successful git branching model by Vincent Driesen well the schema it's not the diagram is not necessarily the most it looks a bit messy but it's because it's so small so basically we are using the developed branch for development the master branch is the blue one over here it's only used for releases there you have the text for every release and then we have different branches for features bug fixes and maintenance and they also they all follow a consistent naming like feature slash fade 1 2 3 4 fade is the feature and enhancement tracker that is using it's also open source you can find it as open fade it's also used in open Sousa for suggesting new features and discussing feature implementation or bug fix BSC is bugzilla Sousa.com and then the bug number so we are trying to have a very consistent branch naming people work on their own branches and when they are done with it they submit a merge request through github and we are using we recently started using the new review feature from github maybe I can show it later if people don't know it yet that's actually something very nice yeah and we are using this tool called git flow well oh there's a typo it's it's not F but it's V git flow AVH that's a fork from the original git flow tool so git flow is an extension if you have a git repository you type git flow in it in it once it adds some values to the configuration file that you can for example the naming of these branches the prefix feature bug fix maintenance yeah it's a helper to implement this branching model and you can modify the configuration as you like but it makes sure that you have consistent naming when you want to open a new feature or you start working on something you type git flow feature BSC 1234 start when you're done you would use git flow feature finish but we no longer use this but use github's reviews merges instead yeah at github things get reviewed thing and then we try to squash squash all the commits into one so that and then they have a meaningful commit message that you can later cherry pick the whole feature or the whole bug fix without having to cherry pick 20 individual fixes but one one commit only yeah so much for the branching model now the bigger picture so we have three main sources for input either through fate which I already mentioned through Buxilla partners or employees file bugs because they found a bug in the documentation or through a system that is called doc comments I'll get to that later after that we do evaluation and planning to be honest that's why I don't write it out there we are using Trello for the organization a lot of you are probably using it personally I don't like it I don't like it because it's not open source obviously we are or I'm trying to push people to use fabricator instead or something else but yeah there's plenty of tools I mean you can use when it comes to tracking there's there's so many open source tools out there but nowadays I mean I'm old school I use Buxilla or something like that or it in Fedora we use Buxilla a lot but nowadays people want to have these work boards and they want to have nice drag and drop in the browser and whatnot so we use Trello that's important when it comes to planning we assign resources we have we have this team of like 13 and we have these tasks to do and we have an estimation of how much every task is so you pick your Trello cards this is what I'm working on yeah that's really so the resource planning is actually something I forgot here we have gun charts as well but I don't do them and I don't know what the software is called for doing it yeah after the planning comes the research usually when there's something new you need to research it first you cannot just start documenting it straight away I mean if I knew everything I wouldn't be yeah well there's nobody who knows everything actually we do have some documentation writers who know more about certain things they are focused on storage for example and they know they have so much they have accumulated so much knowledge over the time but usually when there's something new you first sit down with a developer for like two hours and he explains this new feature yeah then comes the documentation this is where all the the unicorns are born and and everything yeah it's it's sometimes it's hard work but it's just writing the the stuff and I think I've explained the toolchain already so let's just say it's magic after that we send it to the developers for feedback it's not yet published some of the documents are then translated and then they are published on the website later so one thing but that's actually we are not done once it's published I mean it's it's a constant iteration not only with every new SUSE release but with every release of the documentation sometimes we do publish doc updates after the release and also with every feedback we get and the feedback is something that many people forget when they write documentation so we have two main methods for feedback one is you can report a bug so as you can see these are two screenshots from the SUSE documentation from the online documentation and there's actually a report bug at the bottom at the top for every paragraph which automatically opens bugzilla it fills in all the forms which book is it which chapter which everything and then people just need to fill out their feedback or their criticism or whatever they have in the comment field of bugzilla the other system I quickly briefly mentioned it earlier it's called doc comments this is the system that you see here once again in the background we have the XSLT style sheets working the XSLT style sheets again doc book they allow you to for example on the we have the we have a nightly version of the documentation that's generated every night if you click the bug the feedback bug feedback button there you are directed to bugzilla but on the documentation that is that goes live you're directed to the doc comment system which is yeah more intuitive you just need to fill out your email and your name and can provide feedback so for technical people bugzilla is probably the way to submit feedback for less tech-saving people it's probably documents or other people just send us emails to doc-minus-team at susie.com so that works as well but really don't forget the feedback and don't rely on on people I mean make it easy for people to give feedback don't really rely on if the hurdle is so hard high that you require them to submit pull requests on github you probably won't get a lot of feedback so there needs to be a low entry barrier for feedback and the more feedback you have the easier it is the more feedback you get the more feedback you get the better your documentation gets and in the end ideally all questions are answered and yeah no more feedback needed which never happens but all right but so far that works up pretty well and I think compared to other documentation teams we are doing pretty fine we've seen that at the write the doc conference last year where people were telling us what they are planning to do and we figured like oh we are already doing that we are already doing this so on but of course we do have some problems as well well continuous integration that problem was just solved last week but the biggest problem that I see is we are still doing the traditional waterfall thing we have tried to become more agile or more continuous but that doesn't necessarily work there's always a very short time frame between when a feature becomes ready for testing and for documenting and between the release so after the the beta from beta to release of Susan or open through the product we are very very very busy and and don't have time for anything else sometimes we even have to veto features we can do that if the doc if there's no documentation and the feature is useless it probably gets delayed or we need to provide a documentation update later so again the the workload throughout the year is not constant and yeah that's definitely something that we need to address so we are but it's always a question of I mean of course you can do the whole agile thing and document every single feature and every line of code that the developer does but then I'll get to that just a moment but then yeah well you're in this in this never-ending loop you document something if you have a scrum cycle a sprint and after two weeks you figure out oh our developers rent into the wrong direction and let's do it from scratch you have documented something well that isn't there or you have documented it for yeah no it doesn't work out so you start all over again for example screenshots are typical example right before the release we have to go through all these screenshots in the documentation again to make sure they are up to date even if only a tiny thing in the interface has changed you definitely want the latest screenshot all the checkbox or developers keep renaming options or something like that and you're referring to this option not only in the screenshot but in the text so this can become very cumbersome and if you do this last minute yeah also we are decoupled from development that's both a buck or can we just address your question later after that okay I already address it thank you we are decoupled from development that's both both a feature and a buck well people think a developer is the best person to write documentation but he actually isn't I mean he knows the inner workings of his application but he doesn't know the users expectations for him everything is so obvious why would people even ask questions right so you always need or in a perfect world if your organization is big enough you do have a dedicated documentation team or in your community you have some volunteers who do the documentation and ideally they are not the same ones that are also working on the code we inside Susie can bridge this gap by sitting down with the developers but on the other hand sometimes it's I mean sitting down is always very nice but sometimes it's also emails back and forth back and forth 20 times that is cumbersome as well so the coordination effort is very big and the last problem that I see is so the first two problems can probably be addressed with a more continuous and agile approach we do have for example the cloud guys in the in Susie are working with the agile approach they have a dedicated documentation writer in their team who works with the developers every day who follows their sprints so we will probably switch to to a model like that but on the other hand you still need we have this big big big monolithic as I call it documentation like the reference guide or something that's not something that you write on the drive-by while you're developing that's a huge effort and that's where you need the team of documentation writers so we will try something in the in between between an agile and a waterfall approach let's see where we end up with this and to address this monolithic issue the issue of this big monolithic thing we will probably switch to more topic-oriented documentation topic-oriented is the new buzzword when it comes to documentation that's like you have a single task you have a user story you want to go from A to B want to achieve this or that yeah that should be that should lower or should solve some of the problems but on the other hand the traditional documentation the admin guide or the reference guide is not going away anytime soon because people customers wanted they want to have one point of contact where they have like all the options of this program or so deep so the new topic-oriented formats we are using are more like an addition we recently started a series called suzer best practices which will do yeah the best practices for virtualization the best practices for this or that purpose so that's more topic-oriented and now let's go to the lessons we've learned dogs or it didn't happen I mean you all know pigs or it didn't happen for us that dogs or it didn't happen if there's no documentation for you for your app for I mean even if it's just a tiny app I had an app on my mobile I had a problem with it it turned out to be a buck there was a button missing on a certain screen but how was I supposed to know there was no documentation there was no reference design should there be a button or not so you totally need documentation even if some Mac guys tell you that programs should be so intuitive that they don't require documentation you will need documentation period and don't consider your work done until unless you're done with the documentation a feature is not implemented if there's no documentation for it really that's that's things that that also product managers need to understand of course they want everything and they want everything now or they want everything last week but if there's no qa and if there's no documentation then it's not done period yeah as I already mentioned developers should not write docs we are doing it for a good reason don't write about the stuff you know by heart done you know somebody's taking taking photos of these slides yeah you need feedback channels without feedback it's all useless you're running in circles you have no idea what the users expectations are actually are you can do the you can do the long reference guide maybe it doesn't help maybe your users and expect something completely different so if you don't have feedback channels yeah then it's it's not really worth the effort so think about the feedback before you start writing and try to make the feedback as easy as possible yeah you need tools don't try to spend too much time on tooling I mean we didn't write all these tools because we felt oh we need to write yet another tool when we started out there they were just not there meanwhile there there are other tools for example Fedora has at least has had public publican which is something similar to dubs but is meanwhile orphaned I think it's no no longer used Fedora recently switched away from dog book there's for example pondoc that's something similar to what what we do with dubs that can translate between different documentation format and output PDF or HTML and so on so there are already plenty of tools out there if you have any question about a tool or so you can ask me but make sure you have the right tools for for the job to get the job done yeah don't spend too much time on tooling but on the other hand don't try to know don't you have to spend some time on the tooling otherwise the writing becomes too cumbersome but on the other hand don't reinvent the wheel by by writing yet another oh this is solving all our documentation problems there are some proprietary solutions out there which are really awesome but totally useless well for our use case for our use case useless data or something like this I mean there's company making big money with it but it doesn't cater our use case and when we them I mean we had sales agents who were trying to convince us and we tell them we've written our own and we publish it for free they were like what okay start small don't start with a reference guide I mean that's basically at the very top of the of the documentation you start small start with a certain use case try I mean at the very beginning you probably don't have a community of documentation writers or your company doesn't have anyone employed for writing documentation so at the beginning at least at the beginning it will probably be the developer try to see something from the user's perspective and try to try to think of the typical user tasks that a user that the user is trying to achieve and and this particular topic write it down like how do I connect to the mail server or something like that but don't do the I'm covering all menu options of my program and and and all command line options or something like that that's at the very very end of the documentation if you're done with everything else you can do this and last but not least documentation should be open if you're doing open source your documentation should be open and by open I not only mean have your sources somewhere on github I mean we do have our sources on github you can do that whatever you want as I told you before but also try to have an open process that allows the community and allows other people to to give feedback to participate yeah personally we found it it's difficult to encourage the community to to start working on documentation documentation is something that many people take for granted and I only use it when you have a problem as long as everything is fine you don't need it so that's why probably not a lot of people want to work on it but within the community you can do something I mean start with something small like a weekly yeah be open and that's the message I wanted to bring to all of you if there are any questions we have like eight minutes left or something okay first question so the question was how do we manage the localization of our documentation I mentioned the doc manager earlier the doc manager has so at the head of the document you have some some meta text some some additional doc book elements the custom elements and they define whether or not this documentation is translated so for example the install guide is translated into these 20 languages the quick install while the reference guide is only available in English or the tuning guide or the virtualization guide so I think we have like around 20 20 different languages like what we have like some stuff is not translated at all others is translated into six languages and and if when you do the full languages that's around 20 and that's all defined by these meta text within the doc manager we then give it to the translation agency and from there they they go on to to do the actual translations to be honest so the question was how do they do the actual management to be honest I don't know because I don't do the translation myself that's something that we have outsourced you can do this for example this is what we did at co-op at the co-op group or server with tools like trans effects this online translation tool this is also good because it gives people small chunks I mean it's broken down to strings or to paragraphs and people can start working on it so that's something that I would suggest but yeah I can imagine that if you say I have this file in English and I now I'm doing it in in German or something that is difficult but sorry I cannot really give you the answer I don't know what their the translators workflow is I don't think they start from scratch that but they will probably really take our files and overwrite the text but that's just a wild guess and if you're looking for something for a community I would recommend tools like trans effects so you say you don't like Trello because it's closed source but you are publishing all of your work on github what do you think of the current state of tools available on services like github and would you be tempted to try and share some of your learning so the question the question was if I may make it short why we are using github if it's if it's closed source well on github you have the large user base personally I would like to use get lab or something well that's not actually my question my question is what do you think of the state of tools for documentation on services like github and get lab and would you be willing to share some of your experience improve those tools I don't think that integration of documentation I mean they are focusing on code not on documentation for example they can if you're using markup that works markup can be displayed directly in line in github of course it's well the output depends on the browser or so but you get an idea if you look at an XML file in github it's just XML I would love github to have an XML preview but that's obviously not not trivial because then it needs to know the style sheets and whatnot so yeah but really they don't care about documentation much they care about code but the answer to this is treat documentation like you treat code apply continuous integration apply release engineering tactics that you would use for code as well but certainly the tools could be all the services could be improved you had a question as well we cannot so the question was how do we guarantee that the documentation is up to date and I'm sorry I hate to admit it we can't of course we go through it like when it comes to say the screenshots that's a pretty trivial thing you go over the documentation and make sure the screenshots are still up to date but we don't really rework every guide for every release we implement the new features we implement changes but of course there sometimes is outdated information still in there that's where we rely on feedback where we rely on users to file bugs well in a perfect world you would have quality assurance not only for code but also for documentation that somebody really goes through it and make sure it's still up to date but that's something that you cannot really do because of the effort the second one is a very broad question but okay the second question first why not have technical writers as QA for documentation I'm not saying that I'm against it but it's it's the question whether or not if you can afford it if you have somebody only working on QA of docs and also I think that people who do QA I've been doing QA before they should be see things just like the documentation writer needs to see things from a different perspective as the developer somebody in QA needs to see it from a different perspective so actually maybe it a technical documentation writer wouldn't be the best person for QA on docs I would rather have real-world user testing of docs have grabbed people from the street and and tell them to perform this or that if you have topic-oriented documentation it should be easy to give people tasks that they fulfill and then you see if it really works or not that's more interesting than QA so I think we are running out of time for questions okay final questions for those of you who don't have a chance I will be around on the hallway you can grab me there okay you got the one question do you reach out for upstream sure sure we reach out for ups so the question was if we reach out for upstream yes we try to but sometimes it's it I mean if I find something that we work with upstream but sometimes getting stuff back into upstream is very difficult like I recently had something that I needed to document which was some weird behavior of the linux kernel when it comes to epic routing and so the only documentation out there was a five lines of text in a plain text file in the kernel source tree and some comments in the kernel code itself I would love to fix that because then I can say oh I for commit in the linux kernel but as you can imagine the process of getting something accepted is quite cumbersome and at this point in time I'm not doing it but other we usually try to upstream everything all of our work and Susie is actually contributing upstream like we we are doing the open stack documentation for upstream open open stack all right I think that's all thanks very much for your yeah so use our tools breaks them provide feedback send patches thanks a lot