Create a user-guide #280

danieldietrich · 2015-05-27T07:14:18Z

Take a look at asciidoc, gitbook, etc.

danieldietrich · 2015-09-17T08:12:12Z

We need a user guide. What are our business and technical requirements?

which input format, e.g. markdown, ...
which output format(s) (pdf, html, ...)?
infrastructure, e.g. how to maintain/deploy?

Additionally we need a draft of an outline.

RobWin · 2015-09-17T08:16:51Z

Do you want to focus on source code examples?

AsciiDoctor is better than Markdown, if you want to show code examples and highlight important parts.

Do you want to be able to update the documentation on a tablet using just a Browser instead of using a developer notebook with Git and other tools installed?

You could use GitHub, TravisCI and AsciiDoctor for that
Or readme.io

Do you need offline documentation?

AsciiDoctor can generate the same documentation in HTML, PDF and EPUB.

lukaseder · 2015-09-17T08:18:10Z

XML + XSLT = Any format! :)

nousedaccount · 2015-09-17T08:30:49Z

How about markdown. I think Github Flavoured Markdown is sufficient and a lot of people comfortable to write in markdown.

i will take a look to AsciiDoctor.

nousedaccount · 2015-09-17T08:35:33Z

How about integration with javaslang.com website. I think it cooler if documentation available on website too. So reader no need to look at github wiki.

RobWin · 2015-09-17T08:43:29Z

GitHub wiki sucks.
AsciiDoctor documentation looks like this:
http://griffon-framework.org/guide/2.4.0/

As I said Markdown sucks compared to AsciiDoctor, but the syntax is quite similar.

nousedaccount · 2015-09-17T08:51:26Z

AsciiDoctor seem nice.

+1 for AsciiDoctor

nousedaccount · 2015-09-17T09:38:35Z

any idea for draft of an outline?

danieldietrich · 2015-09-17T09:50:47Z

+1 for AsciiDoctor

@RobWin @jasoet-gdp I also thought about using Markdown because of simplicity. But asciidoc seems to be the right tool here. It is also simple but more powerful. It is a standardized way to produce documentation targeting different formats (print, web, ...). Let's take it! Compared to readme.io I prefer asciidoc because we have no vendor dependency and we are free to build our own build and deployment chain with the tools of our choice.

@lukaseder it may be tempting to use XML + XSLT. I've done it years ago with apache fop :-) My resumé: simple things are possible - complex things are masochistic ;-)

danieldietrich · 2015-09-17T09:53:09Z

@jasoet-gdp I will write an outline this evening (GMT+1 here)

danieldietrich · 2015-09-17T09:55:15Z

@RobWin The Griffon Guide looks awesome!

lukaseder · 2015-09-17T09:57:17Z

Why masochistic? It's fun! What do you mean by "complex"? Our docs are all done with XSLT: http://www.jooq.org/learn

danieldietrich · 2015-09-17T10:00:46Z

Maybe I'm a little out-dated here. I used fop 9-10(?) years ago. I'm sure that it emerged in the mean-time.

I prefer non-xml formats for readability reasons (less noise).

RobWin · 2015-09-17T10:12:10Z

No one wants to write text in XML! :)

Have a look at http://www.asciidocfx.com/ as a nice tool to write in AsciiDoctor with a live view.
You can use the maven-plugin to convert AsciiDoc into PDF and HTML and publish it on GitHubPages.
https://github.com/asciidoctor/asciidoctor-maven-plugin

I have a build chain implemented in Gradle.

danieldietrich · 2015-09-17T10:17:06Z

@RobWin there needs to be a business case for lukas. The consumer of the documentation will see no difference I guess. However, a xslt from xml to asciidoc should be seemlessly possible :-)
/cc @lukaseder

RobWin · 2015-09-17T10:22:20Z

But the writer does see the difference, if you dont use a tool for docbook.
Asciidoc can be converted to DocBook as well.

nousedaccount · 2015-09-17T10:41:41Z

Okay. I'll try AsciiDoctor tonight. GMT+7 Here :)
On 17 Sep 2015 17:22, "Robert Winkler" notifications@github.com wrote:

But the writer does see the difference, if you dont use a tool for docbook.

—
Reply to this email directly or view it on GitHub
#280 (comment)
.

danieldietrich · 2015-09-17T10:42:01Z

Great!

danieldietrich · 2015-09-17T10:42:52Z

Note:

We should target all of these output formats: HTML, PDF and EPUB.

Also the documentation should be integrated on the website. Maybe we will open a new tab for now because the website is a single page.

RobWin · 2015-09-17T10:45:08Z

Have a look at Spring Boot Docs too see how they are doing it with Maven

https://github.com/spring-projects/spring-boot/tree/master/spring-boot-docs

Since the documentation is in a Git Repo, you can tag it with your release and link multiple versions on your website. See as an example: http://projects.spring.io/spring-boot/

nousedaccount · 2015-09-17T10:46:31Z

Noted
On 17 Sep 2015 17:42, "Daniel Dietrich" notifications@github.com wrote:

Note:

We should target all of these output formats: HTML, PDF and EPUB.

Also the documentation should be integrated on the website. Maybe we will
open a new tab for now because the website is a single page.

—
Reply to this email directly or view it on GitHub
#280 (comment)
.

danieldietrich · 2015-09-17T10:54:16Z

~~We will remove slice(beginIndex) since it has exactly the same semantics as drop(count) (even if slice() takes an index and drop() take a count).~~

~~However, subSequence(beginIndex) is still needed because it throws on invalid index.~~

Wrong ticket :-) Text went here to: #597

lukaseder · 2015-09-17T10:58:36Z

there needs to be a business case for lukas

Exactly. I can change stylesheet, layout, versioning, formatting, etc. extremely easily using XSLT. But if you don't need that, I agree that XML is more tedious to write. It's always a tradeoff.

danieldietrich · 2015-09-17T11:00:01Z

👍

danieldietrich · 2015-09-17T20:01:28Z

The User Guide should give an overview over the Javaslang 2.x functionality. Here is a draft/first shot of the outline:

Lines starting with - give hints about the corresponding methods/functions, e.g. - memoized.

Tuples
Functions and Lambdas
  Unchecked vs. Checked Functions
  Function Memoization
    - memoized
  Curried Functions
    - curried
  Function Composition
    - andThen
    - compose
  Lifting Functions
  Lambda Type Reflection
    - getType
    Method References
Interface Iterable
  Equality
    - equals
    - eq
    - corresponds
Values
  Capturing State and Monadic Operations
    - get
    - isEmpty
    - map
    - flatMap
    - filter
  Conversion Operations
    - toXxx
  Side Effects
    - forEach
    - peek
    - out
    - stdout
    - stderr
Lazy Evaluation
Controls
  Option: Null Safety
  Try: Failure Handling
  Either: Disjoint Union
  Pattern Matching
Collections
  Interface TraversableOnce
  Interface Traversable
  Sequences
    Indexed Sequences
    Linear Sequences
  Sets
  Maps
  Concrete Immutable Collection Classes
  Arrays
  Character Sequences
  Iterators
  Conversions Between Java and Javaslang
    - ofAll
    - toXxx (see Value)
  Performance Characteristics
Concurrency
  Future
  Promise
Property Checking
  Generators
  Arbitrary Objects
  Properties
  Check Results and Assertions

danieldietrich · 2015-09-18T07:05:58Z

We should add an additional first-level section Idioms, which provides deep insight into the design of Javaslang.

Update: This should be the first section, right in front of Tuples, because it gives a first overview over Javaslang.

Idiom: Static Factory Methods

Javaslang's collection interfaces like Seq, IndexedSeq, ..., Set, ... are similar to Scala's. But there is one important difference: Javaslang does not provide static factory methods for inner interfaces (read: non-terminal types) like Seq. Exception: List, but this is not really an exception, because List is composed of Nil and Cons, so we need factory methods in the List interface.

Example:

// Scala: Seq[Int] = List(1, 2, 3)
val seq = Seq(1, 2, 3)

// Javaslang: Seq<Integer> = List(1, 2, 3)
final Seq<Integer> seq = List.of(1, 2, 3)

What we see is, that Scala provides a default implementation for Seq, which is List. In Javaslang, we keep the (Java) code clean of any kind of implicit defaults, conventions over configuration magic etc. Everything is explicit, the user has to choose the behavior. This makes the code readable and predictable and we are able to reason about it.

Update: There is always an exception. Stack is an interfaces, extended only by List. Scala removed Stack, we keep it to define a clear interface for Stack operations.

danieldietrich · 2015-09-18T10:59:53Z

@jasoet-gdp @RobWin in a first step we should setup asciidoc within our project. E.g. by adding it to the pom.xml. The resources should not be included in a 'normal' build/jar. It is ok, if we build it locally 'by hand' in a first step, i.e. it is not necessarily needed to be built automatically with a travis-ci build for now.

Question: Are there any best practices for the (maven) folder/project structure, e.g.

src/main/asciidoc
doc/...
src-doc/...

If we have the build up and running, the second step is to create the outline (without content). It would be cool to see html, pdf and epub at this stage :-)

RobWin · 2015-09-18T11:39:50Z

Is Javaslang a standard GitHub account or an organsiation?
Create another repo or maven module called javaslang-docs and the folder src/main/asciidoc.
Create an index.adoc which includes all other files and specifies some constants. See as an example https://github.com/spring-projects/spring-boot/edit/master/spring-boot-docs/src/main/asciidoc/index.adoc

danieldietrich · 2015-09-18T11:42:13Z

Thx! Javaslang is currently a GitHub account. I hesitated to convert it to an Organization because there is no way back and I don't know the benefits. Can you explain?

RobWin · 2015-09-18T11:44:49Z

Add the AsciiDoctor maven plugin

<plugin>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctor-maven-plugin</artifactId>
                        <version>1.5.2.1</version>
                        <executions>
                            <execution>
                                <id>generate-docs</id>
                                <phase>generate-resources</phase>
                                <goals>
                                    <goal>process-asciidoc</goal>
                                </goals>
                                <configuration>
                                    <sourceDocumentName>index.adoc</sourceDocumentName>
                                    <backend>html5</backend>
                                </configuration>
                            </execution>
<execution>
            <id>output-docbook</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>docbook</backend>
                <doctype>book<
            </configuration>
        </execution>                        </executions>
                    </plugin>

https://github.com/asciidoctor/asciidoctor-maven-examples/blob/master/asciidoc-to-html-example/pom.xml

nousedaccount · 2015-09-18T11:50:08Z

I think its better if javaslang converted to Organization. So more people (github account) can associate with it.

For AsciiDoctor there are a lot of example using maven plugin https://github.com/asciidoctor/asciidoctor-maven-examples. We just need to pick what we need.

@danieldietrich so, which repository that we will use to store User-Guide. I think its better if user-guide repository separated from main javaslang repository.

RobWin · 2015-09-18T11:51:33Z

In an organisation you can have multiple repos under one common name and you can create teams and add members to teams which are allowed to contribute to different repos.

nousedaccount · 2015-09-18T11:55:20Z

@danieldietrich @RobWin and if javaslang in an organization, we can create a repo contains example usage for javaslang in conjunction with other framework such as Spring Framework, Spring Data JPA, Jackson JSON Module, etc. And assign team to maintain each repo.

danieldietrich · 2015-09-18T20:32:50Z

@jasoet-gdp @RobWin this all sounds really exiting. The only stopper of progress can be only 'fear' - as always in life... My fear is to loose control, e.g. about growth. Let me sleep one night about that and I will create an organization :-)

danieldietrich · 2015-09-18T21:43:45Z

@jasoet-gdp @RobWin Done. Javaslang is now an organization. Feels good :-)

danieldietrich · 2015-09-18T22:56:55Z

Wooaah - this turns out to be complicated. Whom to invite to the organization an whom not??

danieldietrich · 2015-09-18T23:00:06Z

@jasoet-gdp @RobWin I've created a new repo javaslang-docs. You will get write permissions there when joining the organization.

RobWin · 2015-09-18T23:05:26Z

You dont have to add us as Team members. We still can and should contribute via PRs.

danieldietrich · 2015-09-18T23:08:05Z

Ok. What is your suggestion regarding whom to invite to take part of the open source organization? How do other ~~companies~~ organizations it?

danieldietrich · 2015-09-18T23:09:52Z

I like to have a team of committers - active or not.

danieldietrich · 2015-09-18T23:15:02Z

PR's are important. They need to be mentioned in the CONTRIBUTION file (which needs a rewrite). I like the Typelevel Scala CONTRIBUTION.md.

danieldietrich · 2015-09-23T23:14:12Z

Documentation has now its own home (and issues). We close this ticket. Next we will create an outline.

See vavr-io/vavr-docs#7

danieldietrich added the documentation label May 27, 2015

danieldietrich added this to the 2.0.0 milestone Sep 17, 2015

nousedaccount mentioned this issue Sep 21, 2015

Write Outline Draft vavr-io/vavr-docs#7

Open

danieldietrich closed this as completed Sep 23, 2015

Create a user-guide #280

Create a user-guide #280

Comments

danieldietrich commented May 27, 2015

danieldietrich commented Sep 17, 2015

RobWin commented Sep 17, 2015

lukaseder commented Sep 17, 2015

nousedaccount commented Sep 17, 2015

nousedaccount commented Sep 17, 2015

RobWin commented Sep 17, 2015

nousedaccount commented Sep 17, 2015

nousedaccount commented Sep 17, 2015

danieldietrich commented Sep 17, 2015

danieldietrich commented Sep 17, 2015

danieldietrich commented Sep 17, 2015

lukaseder commented Sep 17, 2015

danieldietrich commented Sep 17, 2015

RobWin commented Sep 17, 2015

danieldietrich commented Sep 17, 2015

RobWin commented Sep 17, 2015

nousedaccount commented Sep 17, 2015

danieldietrich commented Sep 17, 2015

danieldietrich commented Sep 17, 2015

RobWin commented Sep 17, 2015

nousedaccount commented Sep 17, 2015

danieldietrich commented Sep 17, 2015

lukaseder commented Sep 17, 2015

danieldietrich commented Sep 17, 2015

danieldietrich commented Sep 17, 2015

danieldietrich commented Sep 18, 2015

danieldietrich commented Sep 18, 2015

RobWin commented Sep 18, 2015

danieldietrich commented Sep 18, 2015

RobWin commented Sep 18, 2015

nousedaccount commented Sep 18, 2015

RobWin commented Sep 18, 2015

nousedaccount commented Sep 18, 2015

danieldietrich commented Sep 18, 2015

danieldietrich commented Sep 18, 2015

danieldietrich commented Sep 18, 2015

danieldietrich commented Sep 18, 2015

RobWin commented Sep 18, 2015

danieldietrich commented Sep 18, 2015

danieldietrich commented Sep 18, 2015

danieldietrich commented Sep 18, 2015

danieldietrich commented Sep 23, 2015