Writing reports and proposals more efficiently using the AsciiDoc lightweight markup language

An example of how you could use the AsciiDoc lightweight markup language to write reports and proposals more efficiently. This video is part of our Advanced Technical Communication training course bundle.

Transcript

Hello, I’m Ellis Pratt from Cherryleaf.

We’ve just put together a little presentation recording of an experiment we’ve done to look at something called AsciiDoc, and see how it could be used to make the way in which proposals and reports could be done in a faster more efficient way.

So, what is this thing called AsciiDoc?

It’s a lightweight markup language. So it’s similar to something called Markdown if you’ve ever heard of that.

Lightweight markup language are different from word processors like Microsoft Word in that you can just open up a text file, write content for your document, using a particular formatting set of standards for doing things like headings and lists, and just save it with extension that these lightweight markup languages use.

In this situation for AsciiDoc, that’s with the extension .ADOC,  and you’ve just saved your AsciiDoc file.

So this means it’s a lot quicker and faster than launching Word and waiting for Word to kick off.

And with the lightweight markup languages, the way it looks, the look and feel, the formatting, the colours, and size of the headings and so forth, are stored separately.

Like with web pages, or content for that type of thing, is stored as a cascading style sheet file, the same type of thing happens with a lightweight markup language.

So what this means is, if you’re copying and pasting content from one document to the next, you don’t have some of the issues that you get with word where the formatting comes with it and all your bulleted lists of your fonts start to suddenly go out of kilter.

So AsciiDoc is an alternative to Markdown.

Markdown was probably the first lightweight markup language around, and it began with a very limited set of features, and as it grew in popularity, people wanted it to do more and more.

And as a result, there’s been an introduction of new versions of Markdown with extra features.

So rather than there being one generally accepted standard for what Markdown is, there’s a number of different versions and flavors; some of which are supported by some tools or platforms. and others which are not.

So that causes some challenges, in that the way in which you write your Markdown file might not be supported by a place where you want those pages to appear.

And also, it still might not have all of the features and functionality that you would like it to have.

So AsciiDoc has come along.

It’s based on an XML standard, and there’s just one version of AsciiDoc, and it has a lot of features within it.

So to use AsciiDoc, you can write content in any text editor that you like.

So it could be Notepad if you want.

If you are a developer and you’re using something like Atom or SublimeText, you can just write to open up a new tab. write your documentation as you’re writing your code, and hit Save.

There are some dedicated authoring tools, such as one that we’ll look at called AsciiDocFX, and another one called Brackets.

These two for the Macintosh, which gives you the option of previewing what your content will look like when it’s converted to be a PDF, or converted to be a web page, and so on,

So the way in which you write content in AsciiDoc is that  you use some formatting codes to make certain elements headings or bulleted lists or numbered lists

And the formatting is a pretty simple and straightforward way of writing.

Pretty easy to remember.

So for your title of your document you just have one equal sign .

If you’re going to have a level one or a heading one within your document, you do two equal signs heading ,or level two, three equal signs and so on.

Normal text – you just start writing.

If you want to have a bulleted list, do you just use the asterisk key on your keyboard, and you write your items, each one with an asterisk preceding the item.

And when that is converted to HTML or to PDF, that appears as a bulleted list.

And if you want sub-lists, indented in sub-item in a bulleted list, you use two asterisks.

And if you want a numbered list, and so on, you use the full stop (or in American, the period symbol).

And sometimes, you want to control where the page breaks are.

So that one section ends and the next section begins, and you can set it so that there’s a new page break at the start of every level heading.

Alternatively, if you want to control specific places you use the < sign, you do four of those ,and

that generates the page break.

And that’s pretty much all the formatting instructions that you need to be aware of and so from your AsciiDoc file.

What happens is, to use it, it runs through a conversion process built into some of the authoring tools, like AsciidocFX, the capability of just saving as HTML or PDF, or epub automatically.

You can also run a program called Asciidoctor, which can do that conversion for you by the

command-line, and that can be handy if you want to start automating the generation of documents.

So you can output it to be a web page as .html, and you can apply different style sheets to things.

So you can output a page to look like slides, such as the slides that we are looking at now, and you can also generate the content to look like a standard web page.

And, in fact, there are also tools that can generate web pages with left and right navigation top

navigation bar, and the like.

So you might want to write your content in AsciiDoc and use that to generate a website.

For proposals and reports, the most common thing is to generate it in a printed format as PDF.

And as standard, you can generate your AsciiDoc files to be .pdfs, like an article, which is probably how you’d want it to be for a sales proposal or report, or as a book.

You can also generate to ePub and to an XML standard called DocBook, which is also a way in which you can generate Word documents if you want.

So let’s look at some of the more advanced features that you have within AsciiDoc.

So one thing you can do within your page of text that you’ve written in AsciiDoc is you can include text from another document in it.

So what you can do is you can build a document or proposal and the like, from a collection of other files or other pages.

So in the context of writing a proposal or a report, what this means is you can delegate the writing to

different people.

You can include a legal page or a legal topic, and you can say to the legal department, here’s the page where we’re going to have the information about the legal issues. If you write that content, what will happen is that it will be included automatically into the report.

If you’ve got people’s CVs, these are the types of things that change over time. People acquire new

skills or they go from having 10 years experience to 11 years experience. You can say to people, here’s your profile – you keep it up to date. When it changes – your experience and so on – you change it.

And then whenever we do a new proposal, that will be automatically included

And price lists.

You might want to include items like price lists or standard technical specifications, and they can be stored in a separate file, controlled by the people that know that particular information.

And then that can be included embedded, as it were, in the document.

So this is different  from copying and pasting, because if you copy and paste, one of the downsides is that you might not have the latest information that’s coming across.

And it can be quite time-consuming.

You might not have the correct source material to copy and paste.

And of course if anything changes between the time that you paste it into your document and you publish it, then that’s not going to be reflected in your document.

And so one approach for writing proposals is to have like a build page.

And this is a page for your document, and what you do in that is you include all the different pages that you want in your proposal or in your report

Now the syntax or code for that, is a little bit more complicated than it was for doing things like the bulleted lists.

What you do is you write the word “include” , you use two colons, and then you have the file name for the file that you want to include in your document, and then an open and a closed square bracket.

Another thing you can do within AsciiDoc is you can have variables.

So, for example, you might create a standard report or a standard proposal, and in it, you include

the company name or the contact name at different points.

And of course within every different proposal or report, the company names is likely to change .

So what you can have is, in your document, reference to a variable.

And the way that you have that is you use the curly brackets for that variable, and then either at the top of the document or within a separate file in the separate topic, you define what that variable will

be.

And the way in which the variables are written is you have a colon, the name of the variable and another colon, and then what that value is.

So if you’ve got a variable all the way through your document called {company}, then either in at the top of the document or within a separate “variables” topic, you would have “company:” and then the name of the company.

So that’s great for things like somebody’s name contact name or a product or service.

So, it’s like a mail merge as you would have in Word.

Another feature that can happen within proposals is that you don’t want standard text for every proposal .

Some people are in different scenarios different situations and you want the text to adjust.

It might be there in a different country, and therefore the contact names for that country might change, or the services available in that country might change, or you might have a proposal for different products and services .

So, you might have one collection of services which relate to writing policies and procedures and another set of services about writing and user documentation if you’re a technical writing company like Cherryleaf, and things like the client list might vary depending on what it is that somebody wants to buy.

And the case studies that you might have might vary depending again on the situation or the scenario .

So, you can mark-up text within the document and say this is relevant to one condition and this is relevant to another condition .

So, for example, if we take the example of policies and we want to say this is the text that we want to appear when somebody is interested in our policies service, then what we can do is tag it using this markup, and then that can be identified as relevant to situations when somebody’s interested in the policy service.

And then what we can do is in our variables file, if we say that the policies exists then this bit of text will appear in our finished document. That’s one way we can do it .There are a number of different ways you can use conditional text.

So, we’ll look at an example where we put this all together the idea of a build page with different variables and some conditional text .

So, let me walk you through how we created this proposal using AsciiDoc.

And so we have pages of content with a header and some page numbers at the bottom .

So, we talked about a build file, and what we have is we have a document a build file that is used for every new proposal.

And in it you’ve got all the different pages that need to be included in the proposal that every page effectively is a separate file

And at the top is some instructions on the locations of certain files.

One of those is a cover page which includes the logo and the company address and information like that.

In the cover page is a command for including a table of contents in the document, which appears in the build file now within this build file

There are some topics which are going to be unique to the particular proposal report that you’re writing things, like the understanding order client needs or our clients timescales or how are you proposed to deliver the solution .

So, there might be a topic about the understanding of what the client needs, and this might be blank and the person’s writing the report proposal just creates the content from scratch.

Or there might be some text to guide them through writing that particular section there are other pages which you want in every proposal things like the legal information, and we store information that is going to be used across lots of different proposals in a separate folder, what we normally call an inclusions folders .

So, things like people CVs or text that always appears like the next step (that you want a purchase order), or the legal information or common information about the company itself that doesn’t really change, then we have that in the inclusions folder .

So, here for example is the standard legal information about the payment terms .

Some pages have text that’s tagged for different situations .

So, for example when describing the company, we have text that emphasises a certain service it could be policies and then for those more generic proposals or reports .

Some alternative text that would appear instead all the variable information and the conditions that we want to set we store in a single file and this week all the variables file, and this could potentially be generated by having a form that a customer or a sales person, depending on the type of document you’re creating, that they fill in on a websites or elsewhere. And as a consequence of that form being filled, in a variables document is automatically generated and placed in the appropriate place .

So, in this example the variables file will be filled in by a sales person, and the types of variables are things like the company name the contact person what’s being proposed when it’s going to be need to be delivered, the date, the proposal, that type of information.

And then one condition which varies for this particular proposal, and in the green text we’ve got guidance how to turn on or off that particular condition – and that condition is whether this is a proposal promoting services around writing policies, or a more general proposal .

So, at the moment this is set to say yes, this is going to be a document that’s suggesting or proposing the client gets policy services .

So, as a consequence of that, in the case studies ,we have a case study that appears which is about writing policies.

If we change that variable to be off, we could have yes or no, we’re using a way of doing it like this, and we go to where the case studies were previously, that text has now changed

And instead of having a case study about writing policies, we’ve got more general quotations from clients, because the page that we have about case studies has been marked up.

If it’s not the condition for policies, then we have quotations.

If it is then about policies, then we have a case study about policy writing.

So, if we want to create the PDF what we do is we generate build file as a PDF document .

So, we go to PDF in this particular tool hit Save as that could be generated automatically.

If you wanted by using Asciidoctor instead of the built in saving and publishing capabilities of the tool that we’re using in this situation.

And here’s what’s generated from AsciidocFX when you save as a PDF and you have it set to be an article and not a book .

So, this is using the standard template and the standard fonts and look and feel and so on that come with the application.

You can go in and adjust the publishing templates so they have different fonts different sizes and so on.

You might want to have the logo appear in the header, or have the page numbers in a different place. You can do all of that, but in this situation this is just straight out the box how it would look.

So, just to summarise what the benefits are of taking this approach

It’s fast. You can just write when you need, using a text editor very quickly.

You can just open it up and then save that document with that AsciiDoc extension and the tools that have .

Some of the previews for AsciiDoc built-in and automatically can convert the AsciiDoc files to be pdfs or to be web pages are free and you can do a lot with it.

It’s quite flexible in the way in which you can set conditions and how the content appears

You can have content presented as slides and you can have content presented as web pages

And it’s pretty easy to learn. It doesn’t take too long to learn that syntax.

And what you can do is you can build up a collection of topics that can be reused across different situations, different documents, and if you make a change in those collections of topics, those included files then that will ripple through to all of the future documents that are required.

And you can start to run scripts to generate the documents with certain conditions .

So, you potentially you can have a form on your website that says you tell us which country you’re in or which product you’re interested in or service, and that can then set the variables for the variable for. And then when it’s published, it will publish a version of the document specific person .

So, personalised to that particular end-user now .

Some downsides to it.

It doesn’t have the capability that you get with tools that have built in link management and content management, where file name changes, it adjusts all the links .

So, that the document still works if you change a file name in your collection of files, then that file won’t be included when you go to generate your document it has .

Some limited spell-checking but not the sophistication that you get with Word.

And with the tools like AsciidocFX, there is a preview, but it’s not WYSIWYG in the same way that it is with Word.

And there is a little bit of syntax around that needs to be done to do this more sophisticated publishing, which is a bit more technical than Word.

So that’s really the example that we’ve put together we’re going to make the violence available free of charge to people that subscribe to advanced writing courses if you want to build it yourself you can review the video and go back and you can see how we created and built the files but if you’ve got any specific questions then you’re more than welcome to email us at info@cherryleaf.com.