Blog or docs?

[gdalle]

See the pretty convincing discussion on Discourse: https://discourse.julialang.org/t/write-documentation-prs-not-blog-posts/100942/

In the short term, it feels more motivating for me to see results and progress immediately, so I vote to keep this website as a place to coordinate drafts and add new content.

In the long term however, I do agree that all of this belongs in the official docs. Does it make a difference if we move the website format from Franklin to Documenter, so that future transfer becomes easier? In any case we could annotate each section with a link to where it belongs in the docs, and set up a way to monitor progress when the time comes to contribute back.

What do you think @jacobusmmsmit @adrhill ?

[adrhill]

In the short term, it feels more motivating for me to see results and progress immediately, so I vote to keep this website as a place to coordinate drafts and add new content.

I agree. Until this guide matures, it's easier to open issues to coordinate in here. Opening issues in the JuliaLang/Julia repo would add quite a bit of noise.

ToucheSir's comment in the Discourse summarizes my thoughts well:

IME this is what kills the momentum of many docs PRs, and as a maintainer who is frequently guilty of requesting multiple rounds of revisions to grind down someone’s hard work into a form which fits the existing docs I’m at a loss for how to fix it.

I propose we go through this process once we finalize a section in here.

Does it make a difference if we move the website format from Franklin to Documenter, so that future transfer becomes easier?

This sounds reasonable. Is the difference between the two formats large enough to make this an issue?
(On an off-topic note, it would be nice to have Pandoc readers/writers for these formats.)

Another aspect that we should discuss is the writing style. To be upstreamed to the Julia docs, the guides would have to be written in a more formal style than e.g. contents from #4.

[gdalle]

ToucheSir's comment in the Discourse summarizes my thoughts well:

Indeed, excessive PR reviewing stifles contributions. At least at the beginning of what we're doing here, I propose we add things without systematically waiting for each other's feedback. I set up a branch protection so that PRs are necessary but reviews are not, so feel free to merge within reason.
However, we should probably coordinate on the project https://github.com/users/gdalle/projects/6 to avoid duplicating work

[gdalle]

This sounds reasonable. Is the difference between the two formats large enough to make this an issue?

Not really, it's mostly Markdown. The only thing is, there is necessarily gonna be a lot of rewriting when the time comes to contribute to the docs, whereas submitting it to the Julia blog would require much less editing. Since I'd like us to do both, I actually would prefer keeping Franklin (plus it looks prettier)

(On an off-topic note, it would be nice to have Pandoc readers/writers for these formats.)

Literate.jl does something quite similar

[gdalle]

Another aspect that we should discuss is the writing style. To be upstreamed to the Julia docs, the guides would have to be written in a more formal style than e.g. contents from #4.

I'm open to being more casual than the official docs, again the first step in my view is to submit this as a blog post. However, let's keep it always respectful and inclusive

[jacobusmmsmit]

My thoughts:

• Less formal style than docs, more "storytelling", explanation and how-to than infodump.
• Franklin > Documenter
• I agree that we should add things without much feedback apart from ensuring coherence, particularly in assuming that something that you expect to be spoken about is actually mentioned in a previous section.
• I will, however, do comments/PRs on grammatical correctness :P
• We should agree to write in either US or UK spelling. I don't mind as long as we can agree :)

[gdalle]

Sounds good to me! I'm more used to US spelling but none of us is a native speaker so let's not be too picky on weird syntax, at least at first

[jacobusmmsmit]

Ok we can do that after then :)