Asciidoctor :: Discussion

Big-big-fat multi-module projects

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

4 messages Options

Victor Romero

Sep 16, 2014; 3:54pm

Big-big-fat multi-module projects

I'm trying to figure out how I could use asciidoctor to document a really huge multi-module opensource project.

The neo4j manual seems to use python's asciidoc in a uber complicated fashion but with a very intersting result.

It seems that they generate documentation jars with a specialized maven plugin and then they create the single, browsable, searchable, multiproject, documentation site.

I'm wondering if someone has acomplished something similar with asciidoctor and if he/she would like to share the experience?

Thanks

mojavelinux

Sep 16, 2014; 8:52pm

Re: Big-big-fat multi-module projects

Administrator

Victor,

It's funny you should ask that because we are looking right now at how to migrate the Neo4j manual to Asciidoctor. We'll definitely communicate our approach and findings as we go along. But first, we need to sort it out.

Ideally, the goal is to get the docs to work as well as possible outside of the Maven build. This encourages participation from non-developers and makes it less of a hassle for developers and non-developers alike (aka tooling friendly). There's definitely a balance between what is generated and where it ends up. Too much dynamic behavior makes it pretty meaningless outside of the build environment. Too little dynamic behavior makes it too manual. The key is to strike a balance, or rely on caching of the dynamic bits.

As I said, there's still a lot to sort out. This is the main architecture challenge we'll be tackling in the coming months.

If people have ideas about how to organize docs, I encourage you to share. As you talk through it, you might find even more ideas for how to organize your content.

Cheers,

-Dan

On Tue, Sep 16, 2014 at 9:54 AM, Victor Romero [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I'm trying to figure out how I could use asciidoctor to document a really huge multi-module opensource project.

The neo4j manual seems to use python's asciidoc in a uber complicated fashion but with a very intersting result.

It seems that they generate documentation jars with a specialized maven plugin and then they create the single, browsable, searchable, multiproject, documentation site.

I'm wondering if someone has acomplished something similar with asciidoctor and if he/she would like to share the experience?

Thanks

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Big-big-fat-multi-module-projects-tp2227.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

Dan Allen | http://google.com/profiles/dan.j.allen

nawroth

Sep 16, 2014; 10:16pm

Re: Big-big-fat multi-module projects

In reply to this post by Victor Romero

Hi Victor!

Nice that you had a look at what we do with the Neo4j docs!

Feel free to ask me about it if you have any questions.

2014-09-16 17:54 GMT+02:00 Victor Romero [via Asciidoctor :: Discussion] <[hidden email]>:

I'm trying to figure out how I could use asciidoctor to document a really huge multi-module opensource project.

The neo4j manual seems to use python's asciidoc in a uber complicated fashion but with a very intersting result.

That's a good description!

As Dan mentions, we'll get it over to Asciidoctor and will make an effort to keep the build less complicated then (and much more JVM-based).

We already use Asciidoctor(.js) for GraphGist:

http://gist.neo4j.org/

It seems that they generate documentation jars with a specialized maven plugin and then they create the single, browsable, searchable, multiproject, documentation site.

The plugin is very simple, it zips together the src/docs and target/docs directories into a jar. The same can be done with standard maven plugins, but for some reason that was a lot slower!

The site is produced by using a slightly forked version of DocBook. I find the idea behind the DocBook webhelp format nice, but the implementation isn't very good. So we're overriding things at a quite deep level to make it work for us. The plan going forward is to get rid of DocBook -- using a more normal template language should make it much easier to make changes to the output.

/anders

I'm wondering if someone has acomplished something similar with asciidoctor and if he/she would like to share the experience?

Thanks

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Big-big-fat-multi-module-projects-tp2227.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

nawroth

Sep 16, 2014; 11:02pm

Re: Big-big-fat multi-module projects

In reply to this post by mojavelinux

2014-09-16 22:52 GMT+02:00 mojavelinux [via Asciidoctor :: Discussion] <[hidden email]>:

Victor,

It's funny you should ask that because we are looking right now at how to migrate the Neo4j manual to Asciidoctor. We'll definitely communicate our approach and findings as we go along. But first, we need to sort it out.

Ideally, the goal is to get the docs to work as well as possible outside of the Maven build. This encourages participation from non-developers and makes it less of a hassle for developers and non-developers alike (aka tooling friendly). There's definitely a balance between what is generated and where it ends up. Too much dynamic behavior makes it pretty meaningless outside of the build environment. Too little dynamic behavior makes it too manual. The key is to strike a balance, or rely on caching of the dynamic bits.

Over time we have evolved into using test-centric documentation in a few different ways. In the beginning it was all based off code, but we're moving away from that more and more over to include tests inside the documents instead. So these documents still make sense, even if you don't execute the tests.

As I said, there's still a lot to sort out. This is the main architecture challenge we'll be tackling in the coming months.

Also, our content layout is kind of modular, even though it's currently not possible to build the manual for a single module. The different modules are getting less important to our users; they rather use Neo4j via REST and don't deal with the individual modules at all. -- We still try to keep the docs in the same module as the implementation, to make it easier to remember to keep it in sync with the code.

If people have ideas about how to organize docs, I encourage you to share. As you talk through it, you might find even more ideas for how to organize your content.

/anders

Cheers,

-Dan

On Tue, Sep 16, 2014 at 9:54 AM, Victor Romero [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I'm trying to figure out how I could use asciidoctor to document a really huge multi-module opensource project.

The neo4j manual seems to use python's asciidoc in a uber complicated fashion but with a very intersting result.

It seems that they generate documentation jars with a specialized maven plugin and then they create the single, browsable, searchable, multiproject, documentation site.

I'm wondering if someone has acomplished something similar with asciidoctor and if he/she would like to share the experience?

Thanks

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Big-big-fat-multi-module-projects-tp2227.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML
... [show rest of quote]

--
Dan Allen | http://google.com/profiles/dan.j.allen

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Big-big-fat-multi-module-projects-tp2227p2228.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]