Big-big-fat multi-module projects

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Big-big-fat multi-module projects

Victor Romero
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
Reply | Threaded
Open this post in threaded view
|

Re: Big-big-fat multi-module projects

mojavelinux
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



--
Reply | Threaded
Open this post in threaded view
|

Re: Big-big-fat multi-module projects

nawroth
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:
 

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

Reply | Threaded
Open this post in threaded view
|

Re: Big-big-fat multi-module projects

nawroth
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.

+1

/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



--



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