-
-
Notifications
You must be signed in to change notification settings - Fork 625
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Create a user-guide #280
Comments
We need a user guide. What are our business and technical requirements?
Additionally we need a draft of an outline. |
Do you want to focus on source code examples?
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?
Do you need offline documentation?
|
XML + XSLT = Any format! :) |
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. |
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. |
GitHub wiki sucks. As I said Markdown sucks compared to AsciiDoctor, but the syntax is quite similar. |
AsciiDoctor seem nice. +1 for AsciiDoctor |
any idea for draft of an outline? |
+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 ;-) |
@jasoet-gdp I will write an outline this evening (GMT+1 here) |
@RobWin The Griffon Guide looks awesome! |
Why masochistic? It's fun! What do you mean by "complex"? Our docs are all done with XSLT: http://www.jooq.org/learn |
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). |
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. I have a build chain implemented in Gradle. |
@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 :-) |
But the writer does see the difference, if you dont use a tool for docbook. |
Okay. I'll try AsciiDoctor tonight. GMT+7 Here :)
|
Great! |
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. |
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/ |
Noted
|
Wrong ticket :-) Text went here to: #597 |
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. |
👍 |
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
|
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. |
@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.
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 :-) |
Is Javaslang a standard GitHub account or an organsiation? |
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? |
Add the AsciiDoctor maven plugin
|
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. |
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. |
@danieldietrich @RobWin and if javaslang in an organization, we can create a repo contains example usage for |
@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 :-) |
@jasoet-gdp @RobWin Done. Javaslang is now an organization. Feels good :-) |
Wooaah - this turns out to be complicated. Whom to invite to the organization an whom not?? |
@jasoet-gdp @RobWin I've created a new repo javaslang-docs. You will get write permissions there when joining the organization. |
You dont have to add us as Team members. We still can and should contribute via PRs. |
Ok. What is your suggestion regarding whom to invite to take part of the open source organization? How do other |
I like to have a team of committers - active or not. |
PR's are important. They need to be mentioned in the CONTRIBUTION file (which needs a rewrite). I like the Typelevel Scala CONTRIBUTION.md. |
Documentation has now its own home (and issues). We close this ticket. Next we will create an outline. |
Take a look at asciidoc, gitbook, etc.
The text was updated successfully, but these errors were encountered: