flink-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stephan Ewen <se...@apache.org>
Subject Website and Documentation Infrastructure
Date Thu, 19 Jun 2014 23:08:31 GMT
I would like to kick off a discussion concerning the project website.

Ufuk, Robert, Fabian, Kostas, and me had a chat today about the website
(and other online contents) and the infrastructure to host them.

As an outcome of that discussion we would propose the following. Please let
us know what you think of it.


1) Project Website with general overview.

Similar to what Mahout offers as a start page. Information about the
project, basic introductions to what flink is, links, status, downloads,
community, infrastructure.

We would like to create the website in using markdown & jekyll and keep
both the markdown files and the rendered html files in the website SVN.

2) "How to contribute" infos

As a part of the website, we would like to include a tutorial on how to
start contributing. This section would include

  - Short summary about how to fork and create pull requests against the
github mirror. Infos how to build and test the code (possibly how to
connect testing infrastructure to your fork)

  - Coding guidelines and how to verify correctness (tests, licences,
headers, checkstyle)

  - A list of issues that would make good "starter" issues in order to
learn the process. Some of us have started using labels in JIRA to mark
such issues, we could simply link a JIRA query there.

Similar to the remainder of the website, this would go into the website SVN
as jekyll flavored markdown and rendered html.


3) Documentation for Flink users.

These docs should explain how to use the system (setup, examples, APIs,
...) We would start with what the current stratosphere website has under
"docs" (http://stratosphere.eu/docs/0.5/) and "quickstart" (
http://stratosphere.eu/quickstart/) and adjust the contents to the current
state and name of the project.

Our thought was to represent all documentation in markdown and make it part
of the code. That way changes to the code and the relevant docs can be done
together. Versioning the code also versions the documentation
automatically. Requests to update the docs come as pull requests or patches
in the same way as fixes for the code come.

We would deploy rendered html files from the documentation once per release
to the website.


4) Documentation about the system internals.

These docs would be relevant to developers, contributors, and others
interested in learning how Flink works. We were thinking about architecture
diagrams for different components and guides like "how to add an operator".

We thought about adding these system internal docs to git repository.
Similarly as the user docs, they could evolve with the code and would be
easy to update or everybody.


5) JavaDocs

The JavaDocs are generated on every maven build anyways, would be pushed
into the SVN for releases.


6) Blog

The blog would be part of the website and come in the same way as markdown.


In addition, we has some thoughts about what to do with snapshot versions
of the documentation and JavaDocs. I leave that to a separate discussion
thread, though.


We are happy to get your comments and what experiences you made with those
approaches.


Stephan

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message