[00:07] Hello. My name is Eduard Lucena. Welcome back to the "Fedora Podcast." We're now doing the episode four. We are here with Jared Smith from FPL of the Fedora Project. Now, one of the core contributors in the docs project. Hello Jared.
Jared Smith:[00:22] Hello. How are you doing?
Eduard:[00:19] Everything is fine. Right now, we're going to talk about the documentation sub-project of the Fedora Project. We want to talk about documentation because we have a former platform with the documentation. Why the whole platform, we don't want to use it anywhere?
Jared:[00:40] I've been in the Fedora docs sub-project for long enough that we've gone through several different tool changes and several different markup languages. Most of our documentation was traditionally done in the DocBook markup language which was XML. It was fairly complicated.
[00:57] Then we used a publishing tool called Publican to convert that DocBook to HTML or to other formats. The tool was a little unwieldy. The markup language itself was quite complicated. It really became a barrier to entry for people that wanted to join the docs project, write some documentation.
[01:19] It was too hard oftentimes to get them to completely understand DocBook and the way it works. We spent more time trying to teach the tooling rather than getting people to write. Over the last year or two, we really tried to focus on changing the formats that we use in the tooling to get simpler for people to join the project, start contributing, easier markup with things like ASCIIDoc, that sort of thing.
Eduard:[01:44] Now we are talking about ASCIIDocs. That's a new toolchain we're going to use with ASCIIDoctor or ASCIIBinder. How this new toolchain is actually better than the old one?
Jared:[01:57] I think the first thing that's better is the choice of a markup language. We're using the ASCIIDoc markup language which is very simple, plain ASCII text.
[02:08] Very simple rules for how to create a section heading, how to create a footnote, how to create a link to another part on the document how to add an image, so that people can focus more on the writing and less on, how do I mark it up to make it look correctly in the documentation.
[02:24] The other thing we've done is then taken a couple of tools out there, ASCIIDoctor to convert the ASCIIdoc document into HTML for a website. Then ASCIIBinder to put several documents together and build an index or a side map for all the different documents so that we can put publisher on all our documentation out there on the web.
Eduard:[02:47] The main idea behind this is to try to get more contributors working in the documentation. How is the onboarding the process in the current documentation team?
Jared:[02:58] It's pretty good. If you want to come join the documentation team and contribute, announce yourself on the mailing list say, "Hey, my name is Jared. I'd like to help write some docs. This is what I'm interested in." Let us know where you might need some help with the tooling.
[03:13] We can help mentor you and guide you through learning ASCIIDoc and the git workflow of putting the docs in a project. It's really pretty easy. Show up. Say hi in the IRC channel or on the mailing list. We'll help you from there.
Eduard:[03:29] The previous version of the docs were meant to be like books, right? What was the main ideas or a thing is that way is to get rid of that kind of format? What kind of docs are we building right now with this new toolchain?
Jared:[03:45] The idea isn't necessarily to completely get rid of these longer, more formal book-style documents, but to augment those and maybe even eventually replace those with shorter, more direct, more action-oriented documentation.
[04:01] For example, rather than have a guide that serves more as a reference and covers every possible value, every possible incantation and every possible way of doing something, we're more focused on what are people actually trying to accomplish?
[04:15] How do we help them solve those problems or make progress on what they're trying to do with as few steps as possible, in a clear, concise, easy to read format that doesn't take 20 or 30 pages to explain?
Eduard:[04:26] The main idea is to show how-to work on it and not to have a proper book then you need to walk all the way to find just a little piece of how to do
Jared:[04:38] Make shorter topic-based documents that are based on the actions that you're trying to perform rather than reference docs that are very descriptive of all the different possible options and how the program works. Say, if you're trying to accomplish task A, do steps one, two, three. Check in step number four to make sure that this completed correctly. Step number five, you're done. That thing.
[05:02] Also, focusing more on small topic-based pieces of help that may be embedded in other larger documents as well. Maybe we have a section on how to format an SD card. You may use that as part of the astronomy SIG or you may use that as part of trying to get an image put under a raspberry pi.
[05:22] There's lots of different places in Fedora. You may want to know how to format an SD card. We could actually take that small little sections that here is how to format an SD card. Then embed that in other documents as needed.
Eduard:[05:35] Last week we had a FAD of documentation. We have a bunch of people that need to work or were to work with documentation. The two questions there, what is a FAD? What do we accomplish in this particular documentation FAD?
Jared:[05:52] A FAD in Fedora it stands for a Fedora Activity Day. Oftentimes it's a couple of days or a few days. The idea of a FAD is to get a core group of people together in the same geographical location and focus on trying to affect some change inside Fedora.
[06:09] In this case, we had a documentation FAD. The idea was to get several people together who had either experience with documentation, experience with these tools or could help flash out the pieces of the toolchain that needed to be finished. Get them together in the same location and really focus on getting some things done.
[06:31] What we pointed out for this particular FAD as our goals were to convert a bunch existing Wiki pages that were some of our most popular searches and search engines, convert those to what we call, Quickdocs, these small documents that are action-oriented.
[06:48] Both to help people learn how to write in ASCIIDoc and get that formatting understood, but also help flash out our toolchain, our tools like ASCIIBinder that builds our site for us. We have some existing challenges with that and we're trying to add some additional functionality around that. Having a set of documents that we could use to test that and continue to drive that development was helpful.
Eduard:[07:11] How many contributors went to this FAD?
Jared:[07:15] I don't know exactly. I think we had 12 maybe, 11 or 12 contributors there at this documentation FAD. It was a little longer than some other FADs. I think it was five days long.
[07:28] It was really a great opportunity to sit down and both write documents, help other people learn how to navigate the toolchain, navigate the gate workflow, navigate the different pieces of the tooling. Also, just make the tooling better and get some real, concrete documentation written out of it.
Eduard:[07:46] We have actually published documents from this FAD or we'll be publishing it in some time shortly?
Jared:[07:58] We have some of the documents that were written and converted during this FAD, published in what we call a staging server. We're still trying to fix up a couple of things in a couple of scripts to do actual publication on the live doc site.
[08:13] I'm guessing, probably, by the time this episode airs that they may have already been published. If not, they'll be coming very soon. That's very exciting to see. At the same time, what you probably won't see just by going to the doc site is some of the underlying tooling that was improved.
[08:29] One of the things that I have to call out, because it's so exciting for me, is that we were able to work with some of the folks that have traditionally worked on the CentOS side of things inside of RedHat on their CI tooling and the continuous integration. We were able to tie that into Fedora docs.
[08:45] Now anytime anybody pushes a new commit into one of these documents, they get repo from one of these documents. If they submit a pull request to one of these documents to fix something up or add some additional information, the CI system will automatically grab that, build a new version of the docs in a temporary website where people can go look and review that.
[09:05] Much, much easier than just looking at the ASCIIDocs source codes. That was another exciting thing that came out of the docs FAD.
Eduard:[09:12] Basically, we have the new platform is divided in the public part of the docs and the staging part of the docs. If I come to the project like a new contributor to work in docs, make the comments I want to be in the doc, staging part. I can actually see my docs
Jared:[09:34] You can actually see them, test them. Make sure the links work. Make sure that they're styled correctly. Once they look great, then we can publish those and push those live to the live documentation site.
Eduard:[09:46] A problem that I had before with the former documentation system, and I think for me being from Latam, from being from a non-English spoken country is that it's hard to translate the former documents to Spanish basically because the platform was intended to be a Flash Book that don't be intended to just translate a section or translate just one part of the document.
[10:15] How this new platform can help us to fix that part?
Jared:[10:20] I think the first thing is there were probably writing less pros and more focused documentation. There's going to be less words to translate, but they're going to be more direct and be more applicable to what the person is actually needing to do or trying to accomplish. I think that's the first piece.
[10:36] The second piece is we're worried less about an overall structure of chapters and sections, and really just focusing on small, precise documents or snippets of documents that can be shared among multiple documentation sets.
[10:51] A paragraph, two or three might be translated and might be used in other documents. By focusing on that re-use, that paragraph doesn't have to be translated over and over again in different documents like sometimes it was in times past.
Eduard:[11:06] Other parts of the project mainly where the parts that produce websites and produce the software itself use a platform that is called Zanata translation. I think we're within documentation sub-project in this change of tools that we are pointing to use that platform to translation, maybe?
Jared:[11:29] That's my current understanding. That can change at any time. As far as I know, we're going to, at least, try to use Zanata as our translation platform and get it working with our ASCIIDoc base markup. That should be fairly easy to do.
[11:46] That's one thing I haven't played with yet that I'm hoping to play with here in the next week or two is work through some of that, the localization and translation pieces to make sure that they work well in our toolchain. If our toolchain only produces English documentation, then I think we failed a large part of our community that doesn't have English as their native language.
Eduard:[12:05] Yes, and that's an exciting part of these new docs because we already have a lot of contributors that work in Zanata. For example, when we were going to do a release, the translation is really fast.
[12:18] We have these translation sprints inside the community than when you just put a deadline mark and say we're going to do this week of translation. You have your award badges or you have your name put it like "you translate that". That's encouraged a lot of people to work on documentation and to work in translations too.
[12:44] For me, that will be a really, really great way to work with it, to use this platform that we already have and we already work on it. We don't have to produce another platform or another tool to work in translation from a platform that we already have.
Jared:[13:01] I think you've hit on a very interesting point there, which is, there are a lot of people who gain a sense of satisfaction because they helped to write a document that helped other people or they helped translate a document into their native language so that other people can help learn that information, can capture that.
[13:18] That really makes their lives better. I'm thankful that I've had the opportunity to learn from other people who've helped me learn, grow and stretch over the years. I want to give some of that back in documentation, help other people learn, and grow. Have that aha moment where they say, "Oh, I figured it out. This works. This is great."
Eduard:[13:36] Well that's awesome news for this platform. Hopefully, we can have documents translated really quick. Like I said before, we have a whole lot of people that work in translation. The translation are really fast. What do you expect in the future with the documentation sub-project?
Jared:[13:57] I think the first thing is, you're going to see more documentation than we've seen in the past. People feel like they don't have to go and either revamp or write a whole new book from scratch with multiple chapters and that sort of thing. It's much more approachable.
[14:13] Someone can take a few paragraphs, a section or a page from the Wiki and convert that over into this format. I think you're going to see both more very documentation, a wider area of topics, so to speak, documented as well as more focused documentation on, what are the things people are actually trying to do?
[14:35] Maybe rather than spending as much time working on a fully complete systems administrator guide, what you're going to see is maybe 10, or 12, or 15, or 20 of the most popular topics of problems people are trying to solve.
[14:48] How do I set up two hard drives to be in a RAID array? How do I change the IP address on a network card? It's really about this concept of what is somebody trying to do? How do we help them solve that problem?
Eduard:[15:04] I think because with the previous format it was really hard to find, for example, just by going to Google and put some words in their search engine. Normally, you don't get the official documentation of the Fedora Project. We're trying to improve that with this new documentation?
Jared:[15:25] Sure, absolutely. One of the things that we've been focused on is we've been revamping the docs toolchain and some of the tools that we used is making sure that the documents don't just look good to a human, but also appear correctly to a search engine.
[15:40] Things like site maps and those sorts of things help search engines to search through the documentation, understand the relationship between different pieces of a document and show up well in search engine results. That's something we've been focused on as well.
Eduard:[15:53] For example, a writer need to focus in somewhere to make his document look good to a search engine?
Jared:[16:01] No, that should be automatically handled on the backend with the tooling that we're using like ASCIIBinder and some of the other tooling that we're using.
Eduard:[16:09] The idea is the writer just write the document. He don't need to be aware of anything behind?
Jared:[16:14] That's right. Write the document. Do your best to write it up in the ASCIIDoc markup language. Other people on the docs team will help review that and make sure it's ready for publication. It's the other tooling behind those things that's going to take care of all the search and search engine functionality so that the writer doesn't have to worry about that.
Eduard:[16:31] For these, we have a bunch of teams working on this. I think we have the continuous itegrations team, We have the website team that will help us to make the look and feel of the website for our documentation feel more integrated with the look and feel of all the other websites we have. Am I right?
Jared:[16:52] That's right. It was interesting at the FAD. We had people who were working more on the tooling side of things and working on the backend scripts. We had people who were very much writers and focusing on the writing.
[17:02] We had a designer that was helping us fix up the CSS style sheet to make the pages look better. We had people, like I said, they weren't necessarily in the FAD, but were helping remotely to get the CI things working. We had people who were very interested in helping other writers by building a style guide and starting to help other writers know how to write, what to do or what not to do as they're writing a document.
[17:26] I think it was a great opportunity to pull the whole core group of people together whether they were able to attend the FAD in person or not. Just put a renewed focus on our documentation efforts. Try some new things, build some new things and make the world of documentation a better place.
Eduard:[17:45] That would be handy. It would be really good to see this documentation project going forward. That's all the time we have for today. Do you have any final thought you want to share with the people?
Jared:[17:56] Just if you're at all interested in documentation and helping make our documentation, we can always use more help. You don't have to be a professional writer. English doesn't have to be your native language, just jump in and help out if that sounds interesting to you.
[18:09] We'll be happy to help mentor you, guide you through the process and help you get your documents out there where other people can read them.
Eduard:[18:16] Well, thank you so much Jared. Bye, bye.
Jared:[18:19] Thank you.