Those aren’t a problem. Stack Overflow deliberately encourages that.
See: Can I answer my own question? - Help Center - Stack Overflow
Those aren’t a problem. Stack Overflow deliberately encourages that.
See: Can I answer my own question? - Help Center - Stack Overflow
I’ll be hanging out in the various channels, to help out with odoc, or Lwt should anyone dare to work on that
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.
I like the idea. But OTOH if the question is due to bad documentation, it’s the documentation that should be fixed…
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.
@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.
Indeed, I think it would be beneficial (sorry for not thinking of it earlier), I added a link on the webpage. Thanks!
I agree. I also would like to clarify a couple of points:
Just a reminder: the OCaml DocJam starts tomorrow!
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.
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 @jeremiedimino @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).
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.
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:
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 types8.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,
andlazy
should be described in the tutorial.
Suggested chapter: Compiler-supported data types8.4 Recursive modules
Still not yet specified.
This is probably the only section that truly belongs to the
“language extension” chapter8.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 | e8.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 units8.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 chapter8.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 alternative8.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 (
)
- Local open in patterns (†)
- Local module (††)
- locally abstract type (††)
- signature
- destructive substitution (††)
- module type of (
)
- 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 (
)
- Compiler-supported data types (††)
- integer and float literals (†)
- lazy (†)
- bigarray (†)
- format string (†††)
- weak (††)
- ephemerons (†††)
- Documenting OCaml
- Extending OCaml
- Going further
- extended indexing operators (
)
- built-in attributes (††)
- builtin extension nodes (††)
- recursive values (
)
- recursive modules (
)
The number of † represents the expected work required to write a good documentation
() : section not ready to be transferred
For this session, I am picking the quoted strings, and then the new exceptions features.
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.
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.
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?