Reference documentation

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

Reference documentation

Emmanuel Bernard
Hey guys,

I might not be looking in the right place but there seems to be a shit
tone of awesome options in Awestruct that are simply not documented. I
keep finding them by walking through other people's repos.

Two examples:

- asciidoc support: except a quick section in a blog post, I did not
  find any doc on how to use it, how to place toc, what are the special
  options etc
- redirect: there seems to be a way to place a .redirect find with some
  kind of content and have it generate the right redirection.

So is there some kind of hidden doc? If not, could we at least capture
the list of features that we would like to document and then start the
work one mammoth at a time?

Emmanuel

---------------------------------------------------------------------
Archives: http://talk-archive.awestruct.org/
To unsubscribe, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Reference documentation

LightGuard
Administrator
Yep, it's the code :(

I know documentation is poor. On my list to improve. Will take pull requests. 

Sent from Mailbox for iPhone


On Fri, Jul 19, 2013 at 11:50 AM, Emmanuel Bernard <[hidden email]> wrote:

Hey guys,

I might not be looking in the right place but there seems to be a shit
tone of awesome options in Awestruct that are simply not documented. I
keep finding them by walking through other people's repos.

Two examples:

- asciidoc support: except a quick section in a blog post, I did not
find any doc on how to use it, how to place toc, what are the special
options etc
- redirect: there seems to be a way to place a .redirect find with some
kind of content and have it generate the right redirection.

So is there some kind of hidden doc? If not, could we at least capture
the list of features that we would like to document and then start the
work one mammoth at a time?

Emmanuel

---------------------------------------------------------------------
Archives: http://talk-archive.awestruct.org/
To unsubscribe, e-mail: [hidden email]


Reply | Threaded
Open this post in threaded view
|

Re: Reference documentation

mojavelinux
In reply to this post by Emmanuel Bernard
Emmanuel,

Probably not the answer you want, but there's no hidden docs :) However, working on the docs workshop Sarah and I presented at OSCON, I have a much clearer picture of what needs to be documented. Suffice to say, it's a lot :)

The Awestruct + AsciiDoc integration is something the Asciidoctor team is going to address, since that's of most interest to us. For the most part, the spirit of that integration is that an AsciiDoc document is portable and shouldn't have any behavior that is unique to the Awestruct environment. There are, however, some very important aspects of the integration that do need to be documented because they deal with how Asciidoctor is configured and how the AsciiDoc content is embedded into the Awestruct layouts.

Right now, the best docs are the slides from the workshop and notes in the workshop repository (which are mostly on the slides).


-Dan


On Fri, Jul 19, 2013 at 11:50 AM, Emmanuel Bernard <[hidden email]> wrote:
Hey guys,

I might not be looking in the right place but there seems to be a shit
tone of awesome options in Awestruct that are simply not documented. I
keep finding them by walking through other people's repos.

Two examples:

- asciidoc support: except a quick section in a blog post, I did not
  find any doc on how to use it, how to place toc, what are the special
  options etc
- redirect: there seems to be a way to place a .redirect find with some
  kind of content and have it generate the right redirection.

So is there some kind of hidden doc? If not, could we at least capture
the list of features that we would like to document and then start the
work one mammoth at a time?

Emmanuel

---------------------------------------------------------------------
Archives: http://talk-archive.awestruct.org/
To unsubscribe, e-mail: [hidden email]




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

Re: Reference documentation

mojavelinux
Ah, I was also going to mention that I think we need to layout the documentation for Awestruct so that it flows from one tutorial to the next much like the new Jekyll docs. In fact, we can use that site as a reference for how we might layout the full Awestruct story.


The Awestruct site is amazingly cryptic when compared to what the Jekyll team now has :)

-Dan


On Mon, Jul 29, 2013 at 7:38 PM, Dan Allen <[hidden email]> wrote:
Emmanuel,

Probably not the answer you want, but there's no hidden docs :) However, working on the docs workshop Sarah and I presented at OSCON, I have a much clearer picture of what needs to be documented. Suffice to say, it's a lot :)

The Awestruct + AsciiDoc integration is something the Asciidoctor team is going to address, since that's of most interest to us. For the most part, the spirit of that integration is that an AsciiDoc document is portable and shouldn't have any behavior that is unique to the Awestruct environment. There are, however, some very important aspects of the integration that do need to be documented because they deal with how Asciidoctor is configured and how the AsciiDoc content is embedded into the Awestruct layouts.

Right now, the best docs are the slides from the workshop and notes in the workshop repository (which are mostly on the slides).


-Dan


On Fri, Jul 19, 2013 at 11:50 AM, Emmanuel Bernard <[hidden email]> wrote:
Hey guys,

I might not be looking in the right place but there seems to be a shit
tone of awesome options in Awestruct that are simply not documented. I
keep finding them by walking through other people's repos.

Two examples:

- asciidoc support: except a quick section in a blog post, I did not
  find any doc on how to use it, how to place toc, what are the special
  options etc
- redirect: there seems to be a way to place a .redirect find with some
  kind of content and have it generate the right redirection.

So is there some kind of hidden doc? If not, could we at least capture
the list of features that we would like to document and then start the
work one mammoth at a time?

Emmanuel

---------------------------------------------------------------------
Archives: http://talk-archive.awestruct.org/
To unsubscribe, e-mail: [hidden email]




--



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

Re: Reference documentation

mojavelinux

On Mon, Jul 29, 2013 at 7:40 PM, Dan Allen <[hidden email]> wrote:
The Awestruct site is amazingly cryptic when compared to what the Jekyll team now has :)

I should add, though, that Awestruct is also tremendously more powerful :)

Reply | Threaded
Open this post in threaded view
|

Re: Reference documentation

LightGuard
Administrator
This is good, but I'd like to take a more divergent guide instead of simply being linear.


On Mon, Jul 29, 2013 at 7:40 PM, Dan Allen <[hidden email]> wrote:

On Mon, Jul 29, 2013 at 7:40 PM, Dan Allen <[hidden email]> wrote:
The Awestruct site is amazingly cryptic when compared to what the Jekyll team now has :)

I should add, though, that Awestruct is also tremendously more powerful :)




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

Re: Reference documentation

Emmanuel Bernard
In reply to this post by mojavelinux
I reiterate my offer to help at the margin but the more involved
contributors will have to decide of the general flow of the doc before
we could chunk the work and share the load.

On Mon 2013-07-29 19:38, Dan Allen wrote:

> Emmanuel,
>
> Probably not the answer you want, but there's no hidden docs :) However,
> working on the docs workshop Sarah and I presented at OSCON, I have a much
> clearer picture of what needs to be documented. Suffice to say, it's a lot
> :)
>
> The Awestruct + AsciiDoc integration is something the Asciidoctor team is
> going to address, since that's of most interest to us. For the most part,
> the spirit of that integration is that an AsciiDoc document is portable and
> shouldn't have any behavior that is unique to the Awestruct environment.
> There are, however, some very important aspects of the integration that do
> need to be documented because they deal with how Asciidoctor is configured
> and how the AsciiDoc content is embedded into the Awestruct layouts.
>
> Right now, the best docs are the slides from the workshop and notes in the
> workshop repository (which are mostly on the slides).
>
> Slides:
> http://mojavelinux.github.io/decks/docs-workshop/oscon2013/index.html#31.0
> Repo: https://github.com/graphitefriction/oscon-2013-docs-workshop
>
> -Dan
>
>
> On Fri, Jul 19, 2013 at 11:50 AM, Emmanuel Bernard
> <[hidden email]>wrote:
>
> > Hey guys,
> >
> > I might not be looking in the right place but there seems to be a shit
> > tone of awesome options in Awestruct that are simply not documented. I
> > keep finding them by walking through other people's repos.
> >
> > Two examples:
> >
> > - asciidoc support: except a quick section in a blog post, I did not
> >   find any doc on how to use it, how to place toc, what are the special
> >   options etc
> > - redirect: there seems to be a way to place a .redirect find with some
> >   kind of content and have it generate the right redirection.
> >
> > So is there some kind of hidden doc? If not, could we at least capture
> > the list of features that we would like to document and then start the
> > work one mammoth at a time?
> >
> > Emmanuel
> >
> > ---------------------------------------------------------------------
> > Archives: http://talk-archive.awestruct.org/
> > To unsubscribe, e-mail: [hidden email]
> >
> >
>
>
> --
> Dan Allen | http://google.com/profiles/dan.j.allen

---------------------------------------------------------------------
Archives: http://talk-archive.awestruct.org/
To unsubscribe, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Reference documentation

LightGuard
Administrator
Very true. In our push for 0.5.4 and 0.5.5 documentation should be big. Look for more information in the coming week or two. Thanks Emmanuel for offering to help.


On Tue, Jul 30, 2013 at 7:14 AM, Emmanuel Bernard <[hidden email]> wrote:
I reiterate my offer to help at the margin but the more involved
contributors will have to decide of the general flow of the doc before
we could chunk the work and share the load.

On Mon 2013-07-29 19:38, Dan Allen wrote:
> Emmanuel,
>
> Probably not the answer you want, but there's no hidden docs :) However,
> working on the docs workshop Sarah and I presented at OSCON, I have a much
> clearer picture of what needs to be documented. Suffice to say, it's a lot
> :)
>
> The Awestruct + AsciiDoc integration is something the Asciidoctor team is
> going to address, since that's of most interest to us. For the most part,
> the spirit of that integration is that an AsciiDoc document is portable and
> shouldn't have any behavior that is unique to the Awestruct environment.
> There are, however, some very important aspects of the integration that do
> need to be documented because they deal with how Asciidoctor is configured
> and how the AsciiDoc content is embedded into the Awestruct layouts.
>
> Right now, the best docs are the slides from the workshop and notes in the
> workshop repository (which are mostly on the slides).
>
> Slides:
> http://mojavelinux.github.io/decks/docs-workshop/oscon2013/index.html#31.0
> Repo: https://github.com/graphitefriction/oscon-2013-docs-workshop
>
> -Dan
>
>
> On Fri, Jul 19, 2013 at 11:50 AM, Emmanuel Bernard
> <[hidden email]>wrote:
>
> > Hey guys,
> >
> > I might not be looking in the right place but there seems to be a shit
> > tone of awesome options in Awestruct that are simply not documented. I
> > keep finding them by walking through other people's repos.
> >
> > Two examples:
> >
> > - asciidoc support: except a quick section in a blog post, I did not
> >   find any doc on how to use it, how to place toc, what are the special
> >   options etc
> > - redirect: there seems to be a way to place a .redirect find with some
> >   kind of content and have it generate the right redirection.
> >
> > So is there some kind of hidden doc? If not, could we at least capture
> > the list of features that we would like to document and then start the
> > work one mammoth at a time?
> >
> > Emmanuel
> >
> > ---------------------------------------------------------------------
> > Archives: http://talk-archive.awestruct.org/
> > To unsubscribe, e-mail: [hidden email]
> >
> >
>
>
> --
> Dan Allen | http://google.com/profiles/dan.j.allen

---------------------------------------------------------------------
Archives: http://talk-archive.awestruct.org/
To unsubscribe, e-mail: [hidden email]




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

Re: Reference documentation

ge0ffrey
In reply to this post by Emmanuel Bernard
Emmanuel Bernard wrote
- asciidoc support: except a quick section in a blog post, I did not
  find any doc on how to use it, how to place toc, what are the special
  options etc
Here's a starter:
https://github.com/awestruct/awestruct.org/pull/51