May 2018 OCaml DocJam Thread -- May 18, 19, 20

announce

#21

Those aren’t a problem. Stack Overflow deliberately encourages that.

See: https://stackoverflow.com/help/self-answer


#22

I’ll be hanging out in the various channels, to help out with odoc, or Lwt should anyone dare to work on that :stuck_out_tongue:


#23

Yes, I was thinking that asking questions on StackOverflow would be a good activity for the DocJam. It seems adequate for a 1-2 hour activity and it’s accessible to all. It’s also measurable (“I asked 15 questions!”) and requires little coordination.


#24

I like the idea. But OTOH if the question is due to bad documentation, it’s the documentation that should be fixed…


#25

It might be possible to use the wiki feature of discourse. On this forum, you can turn the first post of a thread into a kind of wiki.


#26

@gasche, do you think the OCaml Documentation Guideline doc would be beneficial to be linked from the DocJam webpage? I think it could help potential contributors who are unfamiliar with e.g. the doc syntax and tools.


#27

Indeed, I think it would be beneficial (sorry for not thinking of it earlier), I added a link on the webpage. Thanks!


#28

I agree. I also would like to clarify a couple of points:

  • I see web search results as documentation. Their source, whether it is official docs, a familiar resource like StackOverflow or an obscure forum matters a little bit but not that much. In the end, the programmer needs to find an answer to their question and they typically run a web search rather than scanning a table of contents.
  • A complete and non-redundant reference manual is essential but not sufficient as it doesn’t leave room for presenting many problems familiar to the reader. For example if the tool is an HTTP library, a familiar problem might be “how do I implement a file server?”. A sample solution would involve combining several features of the library and is best done in a section—or document—of its own. The great advantage is that it can be written and published independently from the rest of the manual (as long as some vetting tells the reader that the source is reliable).

#29

Just a reminder: the OCaml DocJam starts tomorrow!


#30

In case anyone is interested, we started a #doc channel on the discord server for the DocJam. Feel free to use it, the #general channel, the #irc channel, or all of the above.


#31

If anyone is looking for a concrete project to contribute to during the DocJam, the Dune (formerly Jbuilder) project is currently preparing the Dune 1.0 release, and the website needs contributions (especially the faq) from users who have been porting their projects to Jbuilder for the last year.

If you would like to contribute to it, then https://github.com/ocaml/dune-www is the repository to get started in, and/or tag @diml @rgrinberg @avsm or any of the other Dune maintainers. The resulting website is live at http://dune.build (but is currently not publicised as its not ready yet).


#32

Everything I had in mind is written on the DocJam webpage, section “Contribution protocol”.

We suggest the following protocol for each participant. For details,
see the “Details” section below.

  • Decide on a project to look at, typically a project that you have
    used as a beginner in the not-so-distant past (we will discuss
    project suggestions during the event).

  • Perform a small improvement to its documentation, or a series of
    such improvement; if you apply patches to the project, they should
    get into a fresh branch of your clone of the repository.

  • Optionally, request some feedback on your proposed change to other
    participants: create a pull-request from your fresh branch to the
    master branch of your clone, and post it on the DocJam channels to
    ask for feedback.

  • Once you are satisfied with your patches, send it to the maintainers
    of the project. Log the submission in the “DocJam log” that collects
    all our Jam actions.

Feel free to suggest changes.


#33

I think for that I would do a session of extension transfer for Docjam. By that I mean, looking at the reference manual and the language extension chapter. This chapter tends to grow with time if let unattended. Thus, from time to time, I scan the chapter and select a section that seems mature enough to be transferred to the main chapters of the manual. Generally, I do the process in four phases:

  • scan the chapter and get a feeling for the right emplacement of each section
  • select a section with a clear new home
  • move the grammar description to the reference chapter
  • move the examples and the pedagogical

For the sake of transparency, my current result for the first phase looks like

Section by section analysis of the extension chapter

8.1 Integer literals for types int32, int64 and nativeint

There is no chapter for this contents yet.
Suggested chapter: Compiler-supported data types

8.2 Recursive definitions of values

The limitation on recursive values are still in flux.
Moreover, where to put this description? It is an advanced use
case of a basic language construct. Maybe a “Going further” chapter, with
built-in attributes, extension nodes? This sounds a bit like the current
language exception chapter.

8.3 Lazy patterns

There is the recent problem with pattern compilation,
and lazy should be described in the tutorial.
Suggested chapter: Compiler-supported data types

8.4 Recursive modules

Still not yet specified.
This is probably the only section that truly belongs to the
“language extension” chapter

8.5 Private types

Thematically, this could go to the module section. But private type are
closely related to subtyping notion introduced in the object and
polymorphic variants chapter.
A possible small change would be to create a new chapter after the polymorphic
variant change.
A better and better change might be to create a subtyping sequence in the manual
with
Polymorphic variant | Objects | e

8.6 Local open in patterns

Explain in the module chapter with other local opens

8.7 Short object copy notation

Object chapter

8.8 Locally abstract type

Merge with a local module sections in the module chapter
Keep the polymorphic notation until the transfer of GADTs,
(or artificial example in the polymorphism chapter?)

8.9 First-class modules

A new section of the module chapter with an “advanced section” warning
after the one on compilation units

8.10 Recovering the type of a module

@lpw25 has some major change incoming (in 4.08?), so wait for release+1-2 versions
for the transfer.

8.11 Substituting inside a signature

This is an important piece for signature composition
Subsection of the signature section, or new section in the module chapter

8.12 Type-level module aliases

A new section after the compilation section?

8.13 Overriding in open statements

not enough specified yet according to @gasche

8.14 GADTs

Long term work. This need a new chapter.
Suggestion: “Advanced algebraic types”?

8.15 Syntax for Bigarray access

New chapter needed: “Compiler-supported data types” ?

8.16 Attributes

New chapter, at the end of the tutorial.
Suggestion: “Extending OCaml”
Built-in attributes should go the “Going further” chapter.

8.17 Extension nodes

Same as attributes

8.18 Quoted strings

Introduce them at the same time as the classical string literals,
after the mention of escaped characters

  • unicode escape sequence

8.19 Exception in pattern matching

Expand the description of exception in the core chapter

8.20 Extensible variant types

“Advanced algebraic types” chapter?

8.21 Generative functors

Functor section in the module chapter.
Explain the interaction with first-class module in the
first-class module chapter.

8.22 Extension-only syntax

“Extending OCaml” chapter

8.23 Inline records

Core tutorial chapter.
The error message might be a bit too much.
The “Advanced algebraic type” chapter might be another good alternative

8.24 Local exceptions

Core section on exceptions

8.25 Documentation comments

A new “Documenting OCaml” chapter?

8.26 Extended indexing operators

Problems with the current syntax and potential overhaul in sight
wait for 4.08+1-2 releases, “Going further”

8.27 Empty variants:

Fresh wait for 4.07+1-2 releases

In brief, an extended manual may look like

In brief, my ideal extended manual may look like

  • Core
    • quoted strings (†)
    • extensions in pattern matching (†)
    • local exceptions (††)
  • Module
    • structure
      • overriding opens (:hourglass:)
      • Local open in patterns (†)
      • Local module (††)
        • locally abstract type (††)
    • signature
      • destructive substitution (††)
      • module type of (:hourglass:)
    • functors
      • generative functors (†)
    • compilation units
    • aliases
    • first-class modules (†††)
      • generative functors
  • Objects
    • short copy notation (†)
  • Labels and variants
  • Polymorphism
  • Private (††)
  • Advanced examples
  • Advanced algebraic types (††)
    • Inline records (††)
    • Extensible variants (††)
    • GADTs (††††)
    • Empty variants (:hourglass:)
  • Compiler-supported data types (††)
    • integer and float literals (†)
    • lazy (†)
    • bigarray (†)
    • format string (†††)
    • weak (††)
    • ephemerons (†††)
  • Documenting OCaml
  • Extending OCaml
  • Going further
    • extended indexing operators (:hourglass:)
    • built-in attributes (††)
    • builtin extension nodes (††)
    • recursive values (:hourglass::hourglass:)
    • recursive modules (:hourglass::hourglass::hourglass::hourglass:)

The number of † represents the expected work required to write a good documentation
(:hourglass:) : section not ready to be transferred

For this session, I am picking the quoted strings, and then the new exceptions features.


#34

:+1::heart:

This is quite needed.

In the long run, I think it would be better if the manual had a “What’s New” section that just explained what the new language features were in every version, linked to the sections of the manual that got updated, and if new language features went into the “correct” part of the manual every time.


#35

This could be useful for discoverablity. The less stable additions could be marked explicitly as being likely to change in the future.

A downside to this approach is that a user needs to read the whole manual to know what features are considered unstable. I’m not sure which approach would be best long term.


#36

Note that much of what’s in “Extensions” isn’t unstable. I doubt anyone’s going to remove things like the big array indexing operators or the {|string|} stuff, right? So maybe we leave an “Experimental Features” section for things that are unstable, have a “New Features” section for people catching up from one release to another, and integrate the stable features into the main manual?