done-oo Hi and welcome to open office doc talk. My name is Marcia Wilbur and I will be presenting a short journey towards documentation. Originally, this was scheduled as a meeting, due to the virtual nature of the conference. This is now a presentation which is very useful. And please share the information with anyone who might be interested in participating with OpenOffice in a documentation role. The this talk will cover how to join the different roles, documentation, development, lifecycle, documentation driven development, and other items relevant to writing. My name is Marcia Wilbur. I've been in the community like 20 years I've been a technical writer, Senior Technical writer, co author, co developer for like 20 some odd years. right out of college, I wrote Linux essentials using man pages. And that was in cooperation with comp Tia for universities worldwide. I've written a few other guides. I recently I've been doing a Iot development with like speech and vision, computer vision. As well as small board computers, like BeagleBone, Raspberry Pi. And I you know, I'm also a developer advocate, because I am a developer, I you know, advocate for my peers and myself. I'm also a technical journalist. And sometimes I come across things that are interesting to the public, do a little investigation, find out what's going on and then report it to various media sources. So to begin, OpenOffice is an amazing group. It's really a great project. And I really enjoy working with the OpenOffice team, both developers and documentation. So one of the some of the needs that we have are graphics, writing, editing, and test with graphics, if you are graphically inclined, please contribute infographics or put your skills to work with creating icons or editing some of the screen captures. For example, about 15 years ago, internationally recognized that the color red is not really conducive to technical documentation, but really should be used in cases of warnings or emergencies. A lot of places still don't adhere to this standard. However, it's not like a enforceable compliance issue, it's just a matter of red does stick out. And it does, you know, emphasize but really in documentation for software, and amother color could be used. At any rate, we could use some good graphics to express, you know, like, what is the phrase, you know, picture's worth 1000 words. So we don't need a 400 page Get Started guide, we just need a few good images. No, I'm just kidding. I'm just kidding. Um, anyway, I'm, I like to have a library of assets when I work on a project or with a team. So you know, this would be something good. And I know that they're discussing using their git box. And this could be a good place for it, or maybe the wiki somewhere accessible to anyone working on documentation. You know, like you want to do a note, there's an icon for note, right? You know, and making our icons a little more current, as the documentation may have some older icons that you know, anything is appreciated, right. So writing and editing is of course, really essential right now as we are gearing up and creating documentation for OpenOffice 4.1 X and the older documentation is - How can you say it's useful for some people, however, what we're really trying to do is isolate the different operating systems so that the GNU Linux user doesn't need to read through Mac and Windows information. Because that can be really time consuming. And it's there, you know, having a guide with multiple operating systems and multiple screenshots, and not really comprehensive, including all the options and features and focusing on each one is something we want to move away from, at least in my case, my effort is to separate and start with GNU Linux guides. And then we do have someone who joined the project, it's very exciting. He is a Mac user. And I, I would guess that if they wanted to do something windows related, there might be a need for some windows documentation as well. So of course, you know, participation is appreciated. Many of the volunteers have day jobs, and we realize life is hectic, and appreciate any contribution, any participation. The project is a volunteer effort, and we rely on your participation to move forward. So here's how to join, please see our introduction to documentation page, you can subscribe by sending an email to Doc's subscribe at Open Office apache.org. Introduce yourself on our documentation mailing list doc@openoffice.apache.org. org. And we also have a localization list for different translations and languages. So here's the information on how to join the localization effort. Here's how to just join the documentation in general effort. And we have a volunteer wiki, where we, you sign up and create an account. And then you ask for authorization on the mailing list, you'll be able to start editing pages and adding content, like I created an installation guide for Debian based canoe Linux users. So a quick start installation, guide it you know, it begins with purge Libre Office, install, OpenOffice, that sort of thing. Oh, and by the way, this presentation was created using OpenOffice. So it's really, it's really interesting, you can go to openoffice.apache.org slash get dash involved dot html to find out more. So now I'm going to discuss a little bit more about documentation itself. And we begin with the documentation development lifecycle. Now, this is similar to the software development lifecycle, only its documentation. It works hand in hand, I have found that this, this process works very well when working with software projects. So the first thing is requirement analysis. Does the client or do does the project need documentation? Usually, the answer is yes. It depends on what documentation so you kind of understand a little bit about the scope of what documentation is needed. But you need to understand your audience, right. So in some cases, you might have some documentation where it makes sense to have different operating systems together. But with something like OpenOffice, it's really, you know, there are different features for different operating systems, different options, different options located in different areas, you know, that sort of thing. So maybe in this case, an audience analysis would show the need for separate documentation. That's just an example of the audience. You know, I have a template that I use for audience analysis. It also goes into, you know, what are the goals of the user? What's the level of The user because you don't want to write, you know, an eloquent novel, for say, you know, high school students who just want to use it for their assignments, or someone like me creating a presentation for a conference, right. So after that, you can do your document outlining, and this is the fun part, because usually it changes. But this is where you'll be doing your content strategy, organizing, what topics you need, what sections are important in the documentation. Now, I call this prototype, but really, it's your style guides, your templates, all of the documentation to help you create, you know, the docs, and develop the content. And then finally, you're going to develop the content, put it together, format it, do do all of your, you know, processes, procedures, and related content. And then ultimately, a review is good. I like a functional review. I like a technical review, and trademark and brand review, and peer review. So those are several reviews that you know, really can improve the documentation, then ultimately publish it now you can't just publish documentation, you need to maintain it, and update it. That's the fun part. Right? You know, that's another fun part. So that's development lifecycle. Now, with documentation driven development, this is why documentation is important for project not just so that the users can have information that's important, not just so that you can have, you know, QA, review, that sort of thing. Now, one of the main reasons for documentation, or one of the, in my opinion, that documentation is so important is it can drive development and improvement of the software, even hardware, if you're working on a hardware project, right. Using documentation, as you know, the base, you have people involved in, you know, actually using the product, or device, or software. And those people can come up with, you know, ideas and questions that can spark that, you know, development. And, you know, I, I could try to give you an example of one. So, there was a project where there was a hardware device, and that hardware device, the users needed to SSH into. And without any technical writers or technical people on the project, they decided to put a display module on the outside with the IP address, and that way they could SSH in? Well, first of all, you'd need to be near the device, what's the point? You know, like, if it's on your network, just check out your network and get the IP address. Or another thing was the accessibility consideration wasn't there? You know, there was no audio or another way to get that information. And so without technical writers, or good documentation, people, they move forward and produced this boxing that it's, it's okay, but it's not completely as well developed as perhaps it could have been, if there was appropriate testing, participant testing, or a technical writer to ask those important questions. And so, I don't know, whatever happened to that project, if it ever was released or not. But basically, documentation can drive development if you have the right person, or people on the team, because that's another thing you need to have complete transparency, no fear. No, you know, censorship, because if you can ask the questions, and you get some reasonable responses. It can encourage the writers to ask more questions and Therefore, you know, find the root cause of an issue, find solutions, improve the software hardware, you know, anyways, that was I'll read these through, define the project goals, collect the information, brainstorm and analyze ideas, develop solutions, build a model, present the ideas for other to get others to give feedback on and improve the experience. So that's basically a few steps that are involved in documentation driven development. Some of the tools you can use in documentation. Right now, I have templates where needs analysis requirement analysis and audience analysis, these could easily be scripts that are used that, you know, even with a small front Python, or yet or something, you know, is entity, whatever people are using these days, you know, and just like entering the information, as you know, it comes around, and then it could generate, like, you know, form with audience analysis that can be shared with others, you know, you could do like a collaboration thing. And I like this, create an outline tool, like nowadays, you create an outline, or you do the template, like a scout, we call it skeleton kind of thing, where it's like heading one, heading one, heading one, heading one, or Heading Two, heading two, heading to Heading Two, and it generates a table of contents, right. But you know, that's an outline, too, you could do that. Something similar to that to generate an outline. As far as templates and styles, it would be really cool to have a like style tool, right, where you put in the style for your company or your project. And then it runs against the documentation and checks against the style. For example, if your style for your project requires e mail, it could, you know, you run the tool or script and it could check for E space mail, and then generate the report or, you know, diff, whatever, you know, you know, output, and then even correct, have correctable measures for that and you can develop it, develop that draft. And then obviously review, there can be some review software, very, you know, simple like notifications and people that sort of thing. After that, you know, publish it, maintain it, and reuse. Obviously, I'm big, you know, advocate of reuse. In fact, I used to use docbook and DITA and take the XML and use XML and some other you know, like CSS, etc. and take the documentation and make it not just documentation, but you know, convert it to learning modules SCORM compliant learning modules that work in Moodle. So there's a lot we can do with reuse, right? Trademarks are important, we need to respect other trademarks. And we need to respect the fact that some projects don't use trademarks and specifically ask us not to use trademarks like the canoe project. In fact, they that says please do not include any trademark acknowledgments in good new software packages or documentation. So we need to you know, keep in mind that trademarks different from copyright, we also need to keep content and copyright in mind as well. So that's something we need to keep in mind. Keep in mind, um, yesterday, I saw on the list something about we don't use Creative Commons content licenses. For the documentation. I know Apache had some kind of a license, but I didn't see that applied towards some of the documentation in the past. Although I did see the Apache License. I I use gfdl or put everything in public domain. So I don't really you know, use other licenses. However, when working with the project, I you know, we need to find out what licenses are okay. I use GPL four code snippets and documentation, not for documentation. The, you know, this is useful, because some documentation may require code snippets for these types of documents were OpenOffice. I don't really I haven't experienced a lot of code snippets except with installation, you know, bash command here, whatever, you know, like, that's not, you know, I guess that could be considered a code snippet. I don't know. Either way, either way. Okay. All right. There are some examples just look at past us or, you know, talk to your peers. If you have licensing questions, you know, we have a mailing list, we can ask that question, we can see if we can find that answer. Now, writing for accessibility, this is kind of important for, you know, keeping in mind for documentation, because we have a variety of users, and they may need, you know, further instructions. So, you know, accessibility, I did a presentation here at fosdem on accessibility, and paving the way through positivity. So, when writing, keep keep the language clear, concise, avoid using location. And by that I mean, in the upper right hand corner at the bottom of the page, you know, that sort of instruction may not be useful for someone with a screen reader. And avoid using color and instructions, such as the blue button, there may be seven buttons, and if you're colorblind, it doesn't matter if it's blue, or green. How would you know? And then also contrast in the documentation itself. Some documentation, like I said, you know, uses different colors. Like, you know, dark on light, you can't really read it, you know, what I'm saying? Like, make it easy to read. That's pretty much it, you know, what just make it easy to read. All right. This, I wrote, if a writer notices that, you know, there are only visual cues, then maybe informed the developer, but I don't know how relevant that is to open office docs. It's just something to keep in mind, you know? So please, consider accessibility friendly documentation. So, for writing with accessibility, include details, simplified language colors, you know, what's your colors and visual location? Now, here's the thing. How do you have details and simplified language? Well, the language part isn't the details, you can have details. But the simplified language is the easy, understandable, non eloquent language. You know, some people they don't, they don't really do well, with the, you know, large words, for example, I can give an example is that there was recently a proposal for an exemption, not open office, okay, this is different, this is a law thing. And I would say that the big word there's requirement, like some, you know, somehow that was missed, right? Somehow the requirements were missed because of the language, right? The the language of the requirements, so when you're writing and you know, instructions, you know, information, try to keep it simple. And that way it helps with the localization as well. You know, translating can be, you know, a task, if the words are, you know, not easily understandable also avoid using, like slang for localization reasons, right. Um, I should have put that in there. But, okay, that's another, that's another aspect. Okay, infographics. So, here's the thing with infographics. Oh, they're amazing. They look fantastic, right? However, they, you know, don't mean much for someone who can't view them. And so one solution to that is to, if you're going to do an infographic also have audio describing the content on an infographic, or you can use stag hide and add a transcript, embed it with the image and that way someone can extract that embedded text and get more information about the image, I use this for licensing content licensing purposes instead of slapping you know, some, you know, this is gfdl and this and that and that, I will embed a stag in that a text file with Stagg hide and add metadata to the image file. So that's, that's an option. You know, you can use descriptive tags, or just have a description that would be the simple solution, also. But it has to be able to be read by a screen reader or, you know, accessed by someone who can, you know, listen to the information. So, offering a video and an audio version is a nice way also, like have the infographic and a little audio with it, you know, make a short little video or something. So. And I just want to say thank you for everything that you do. The fact that you're even watching this means you're interested in documentation, which is great, because, you know, it's my, you know, lifelong journey. Thank you so much for watching this and I really hope that you'll consider volunteering with OpenOffice. And then I would like to use the rest of the time that's available to discuss any questions you might have about joining or projects or any ideas you might have to improve the documentation. Again, my name is Marshall Wilbur. I'm just one of the many wonderful volunteers over at OpenOffice. And thank you for watching and participating. Have a wonderful day.