Example online help created with AsciiDoctor and Jekyll

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Example online help created with AsciiDoctor and Jekyll

markb
I've started using AsciiDoctor with Jekyll to build online help for my tech writing clients.  I do use Markdown too sometimes, but when I need to reuse content across multiple books I turn to AsciiDoctor for its includes and variables.  I thought you might be interested to see a screenshot of the result.



Here's the URL: https://www.scitechcontentservices.com/images/portfolio/original-size/adocjekmodel1.png

To protect client confidentiality, I've replaced the text and branding with generic content.

As I don't have an IT background, it hasn't been easy to work out some of the technical setup, but I'm happy with where I've been able to take it.  I love AsciiDoctor. I just wish the process of installing it on Windows and setting up a useful publishing toolchain was better documented for non-technical mortals. That's not a criticism -- I just think there's an opportunity to help even more people get to know the technology.

Thanks to everyone who has contributed to this awesome product!

Mark
Reply | Threaded
Open this post in threaded view
|

Re: Example online help created with AsciiDoctor and Jekyll

mojavelinux
Administrator
Thanks for sharing and for the words of encouragment, Mark!

I do agree better installation instructions for Windows is needed. That's one of the goals of migrating the docs to Antora and a new information architecture.

Cheers,

-Dan

On Thu, Oct 11, 2018 at 11:39 PM markb [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I've started using AsciiDoctor with Jekyll to build online help for my tech writing clients.  I do use Markdown too sometimes, but when I need to reuse content across multiple books I turn to AsciiDoctor for its includes and variables.  I thought you might be interested to see a screenshot of the result.



Here's the URL: https://www.scitechcontentservices.com/images/portfolio/original-size/adocjekmodel1.png

To protect client confidentiality, I've replaced the text and branding with generic content.

As I don't have an IT background, it hasn't been easy to work out some of the technical setup, but I'm happy with where I've been able to take it.  I love AsciiDoctor. I just wish the process of installing it on Windows and setting up a useful publishing toolchain was better documented for non-technical mortals. That's not a criticism -- I just think there's an opportunity to help even more people get to know the technology.

Thanks to everyone who has contributed to this awesome product!

Mark


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Example-online-help-created-with-AsciiDoctor-and-Jekyll-tp6514.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Example online help created with AsciiDoctor and Jekyll

markb
Thanks for your response, Dan.

I use AsciiDoctor as my default tech writing tool now. It really is a game changer and I think its use will grow in the tech writing community once there's a greater awareness of it. Very few tech writers know about it yet. If the entry barrier to adoption for tech writers was lower, I think AsciiDoctor could outcompete the standard commercial tools, such as Madcap Flare.

I'm going to set up a test site with Antora to see if it can replace Jekyll for me. The website looks very professional and I'm excited to see what it can do.

Cheers,
Mark

Reply | Threaded
Open this post in threaded view
|

Re: Example online help created with AsciiDoctor and Jekyll

mojavelinux
Administrator
I'm happy to say we certainly share the same vision about the impact Asciidoctor can have.

I'd disagree, however, that few writers know about AsciiDoc. That may be true in some circles, as is the case with any tech adoption, but the overall adoption is extremely strong. I was just at Devoxx and just about everyone I ran into is using it in some way. It's used at Red Hat, Couchbase, Elastic, Vaadin, MuleSoft, Neo4j, Fedora, SUSE, and the list goes on and on. I think the adoption curve is right where we can manage it.

Of course, we shouldn't rest on our laurels...and we won't. We have big plans moving forward, and Antora is a key part of it. Instead of just thinking about the processor, or as an add-on to a site generator like Jekyll, we're tackling the whole documentation site publishing enchilada.

I certainly agree the barrier to adoption can be lowered. That's a perennial goal for any technology stack. Lower, lower, lower. But it also helps to have great advocates like yourself spreading the word. Most of the adoption of AsciiDoc (in the Asciidoctor era at least) can be traced back to someone advocating for it. And I am extremely grateful to those people.

Cheers!

-Dan

On Mon, Nov 26, 2018 at 10:18 AM markb [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Thanks for your response, Dan.

I use AsciiDoctor as my default tech writing tool now. It really is a game changer and I think its use will grow in the tech writing community once there's a greater awareness of it. Very few tech writers know about it yet. If the entry barrier to adoption for tech writers was lower, I think AsciiDoctor could outcompete the standard commercial tools, such as Madcap Flare.

I'm going to set up a test site with Antora to see if it can replace Jekyll for me. The website looks very professional and I'm excited to see what it can do.

Cheers,
Mark




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Example-online-help-created-with-AsciiDoctor-and-Jekyll-tp6514p6616.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Example online help created with AsciiDoctor and Jekyll

markb
Hi Dan,

The Devoxx conference is for developers who would probably find adoption of an asciidoctor toolchain relatively straightforward. I'm guessing the attendees are mostly are software developers and programming-literate writers who write documents such as Readmes, requirements documents, internal API guides, and technical books.

There are a lot of tech writers who would not know about Devoxx but would attend conferences such as the STC Summit, Lavacon, MadWorld, and WritersUA.  These are the writers I'm referring to when I say few writers have heard of AsciiDoctor. They include English majors writing car manuals and manufacturing processes, Biology majors writing instructions for surgeons using surgical robots, and pharmacology PhDs writing inserts that accompany prescription medicines.

In a recent article, Technical Writing Tools: The Ultimate Choice of 83 Experts (2018 UPDATE) AsciiDoc gets only one, minor mention. The thought leaders cited in the article represent the community of writers that I'd love to see AsciiDoctor break into.

I'm thinking about writing a series of articles to try to help lower the entry barrier for writers who have always used commercial tools and may never have used a text editor. If I do, I'll post an update on this forum.

Again, thanks for all your efforts and the efforts of the whole AsciiDoctor team. I think you're onto something big and I'm excited to see how the whole enchilada toolchain develops.
Best,
Mark
Reply | Threaded
Open this post in threaded view
|

Re: Example online help created with AsciiDoctor and Jekyll

mojavelinux
Administrator
Mark,

I agree with your assessment. While we have strong adoption in one segment of IT, there's a whole world out there to whom we can still reach. I very much look forward to reading and promoting your articles. Thank you again for your dedication.

Best Regards,

-Dan

On Mon, Nov 26, 2018 at 2:06 PM markb [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hi Dan,

The Devoxx conference is for developers who would probably find adoption of an asciidoctor toolchain relatively straightforward. I'm guessing the attendees are mostly are software developers and programming-literate writers who write documents such as Readmes, requirements documents, internal API guides, and technical books.

There are a lot of tech writers who would not know about Devoxx but would attend conferences such as the STC Summit, Lavacon, MadWorld, and WritersUA.  These are the writers I'm referring to when I say few writers have heard of AsciiDoctor. They include English majors writing car manuals and manufacturing processes, Biology majors writing instructions for surgeons using surgical robots, and pharmacology PhDs writing inserts that accompany prescription medicines.

In a recent article, Technical Writing Tools: The Ultimate Choice of 83 Experts (2018 UPDATE) AsciiDoc gets only one, minor mention. The thought leaders cited in the article represent the community of writers that I'd love to see AsciiDoctor break into.

I'm thinking about writing a series of articles to try to help lower the entry barrier for writers who have always used commercial tools and may never have used a text editor. If I do, I'll post an update on this forum.

Again, thanks for all your efforts and the efforts of the whole AsciiDoctor team. I think you're onto something big and I'm excited to see how the whole enchilada toolchain develops.
Best,
Mark


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Example-online-help-created-with-AsciiDoctor-and-Jekyll-tp6514p6620.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux