Quick start :) #1419

SubhadityaMukherjee · 2020-09-20T08:28:33Z

Hello!
I made a little quickstart guide to Documenter.jl (Previously mentioned in the forums).

I am not particularly sure where you need the file placed but I added it as a quickstart.md file.
Hope it helps out people who are starting out with Julia and this awesome package 😄

MichaelHatherly

Thanks @SubhadityaMukherjee. I've added a few inline comments.

I can understand the need for more tutorial/quickstart material for getting started with this kind of stuff, especially more "conversational" content. How do you feel it compares to the content of https://juliadocs.github.io/Documenter.jl/stable/man/guide/? What did you find was missing from that, might be worth iterating of it rather than increasing the size of the docs further?

MichaelHatherly · 2020-09-20T08:48:31Z

docs/src/index.md


 The [Package Guide](@ref) provides a tutorial explaining how to get started using Documenter.

+A quickstart version of the guide can be found at [Quickstart]("https://github.com/JuliaDocs/Documenter.jl/blob/master/docs/src/quickstart.md")


This should use a @ref link for the "quickstart" link rather than linking to the source file directly.

Hello @MichaelHatherly . Thank you for the review. :)
I felt that as documentation for someone who knows their way around these things it was perfect. But for someone just starting out with Julia/actually developing, it would be a bit hard to follow as many steps that were not related to Documenter.jl were involved.
I had initially written a post on my blog but I was told that it might be a good addition to the documentation here so the PR.

I will fix whatever you mentioned by tomorrow.
Cheers

MichaelHatherly · 2020-09-20T08:52:05Z

docs/src/quickstart.md

+3. Put your code in the folder called src
+4. Create a folder called docs
+    - Follow this structure if you can (most of this is auto generated)
+      - DDL.jl


"MyPkg" used above, best to just stick with one name for the examples perhaps.

MichaelHatherly · 2020-09-20T08:53:25Z

docs/src/quickstart.md

+      - src
+      - Project.toml (To take care of related dependencies)
+
+        >Tip: If you have a clean repo you can do this to speed up your workflow


Using a !!! tip admonition here might look better.

MichaelHatherly · 2020-09-20T08:54:07Z

docs/src/quickstart.md

+            sitename = "DDL Documentation",
+            repo = "https://github.com/SubhadityaMukherjee/DDL.jl"
+        )
+    ```


Inconsistent indentation in code block above.

MichaelHatherly · 2020-09-20T08:59:43Z

docs/src/quickstart.md

+5. Learn *markdown* 
+
+It will save your life over and over again.
+Here is the best cheat sheet I found to learn it [CHEAT](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)


https://docs.julialang.org/en/v1/stdlib/Markdown/ is the right reference to point to, Julia's Markdown isn't quite standard markdown in some places so would be best to not direct users to something that might have inconsistencies.

MichaelHatherly · 2020-09-20T09:02:25Z

docs/src/quickstart.md

+        - tests
+        - README.md
+        - Manifest.toml
+        - Project.toml


Put this directory structure in a code block rather, since it's nested in a list already the additional nesting doesn't make it stand out enough.

MichaelHatherly · 2020-09-20T09:03:18Z

docs/src/index.md


 See the [Index](@ref main-index) for the complete list of documented functions and types.

+


Unintentional extra blank?

MichaelHatherly · 2020-09-20T11:29:04Z

Quoting @SubhadityaMukherjee's reply outside of inline comments:

Hello @MichaelHatherly . Thank you for the review. :)
I felt that as documentation for someone who knows their way around these things it was perfect. But for someone just starting out with Julia/actually developing, it would be a bit hard to follow as many steps that were not related to Documenter.jl were involved.
I had initially written a post on my blog but I was told that it might be a good addition to the documentation here so the PR.

I will fix whatever you mentioned by tomorrow.
Cheers

Yes, I followed along in that thread and agree with @mortenpi's final comments.

Let's decide exactly where this content fits into the rest of the manual so that it maintains an overall "flow" rather than bifurcating the manual and resulting in duplication. I'd say it probably fits in right at the start of the "Guide" section and shouldn't be very long so that it actually results in a quick start to using the package. Using as much automation in it as well, DocumenterTools or PkgTemplates, should be required and not an optional "skip these steps" kind of thing, so that the steps are kept to a minimum. If we've got the tools to set things up automatically we shouldn't be instructing users to create specific files manually.

I will fix whatever you mentioned by tomorrow.

Let's also get @mortenpi's take on this prior to doing any fixes, just so you don't have to redo things too much.

mortenpi · 2020-09-27T01:02:50Z

Apologies that it took so long for me to reply to this. I do agree with @MichaelHatherly's comments that we should try to see how we can improve the current "Guide" page. I also think it's worth keeping the Divio 4-tiered documentation approach in mind when figuring this out.

I'd say it probably fits in right at the start of the "Guide" section and shouldn't be very long so that it actually results in a quick start to using the package. Using as much automation in it as well, DocumenterTools or PkgTemplates, should be required and not an optional "skip these steps" kind of thing, so that the steps are kept to a minimum. If we've got the tools to set things up automatically we shouldn't be instructing users to create specific files manually.

Yes, I absolutely agree with this.

I think the quickstart should really emphasize PkgTemplates. It does the right thing and removes a bunch of fiddly steps for the user.
It might be good to briefly show the user how to use project environments and explain that docs/ is a separate environment, because I think a lot of users are not familiar and/or comfortable with them.
I do feel that the Guide page is a bit long. Some of the topics there could probably be expanded upon and split into separate pages, with references from the guide/quickstart page.

However, we shouldn't make this PR too big. Perhaps we could condense this particular PR down to be a PkgTemplates-based quickstart at the start of the Guide page? And then make additional improvements in subsequent PRs?

haampie · 2020-10-22T08:37:24Z

docs/src/quickstart.md

+        - README.md
+        - Manifest.toml
+        - Project.toml
+5. Now in the docs folder make this heirarchy


Suggested change

5. Now in the docs folder make this heirarchy

5. Now in the docs folder make this hierarchy

knuesel · 2021-01-24T11:03:56Z

Would be nice to merge this on top of #1451! @SubhadityaMukherjee are you still intrested in working on this?

mortenpi · 2023-11-01T22:11:25Z

Let's close this PR, but hopefully we can address the points raised here as part of #2321.

SubhadityaMukherjee and others added 5 commits September 20, 2020 12:19

added quickstart guide

62caa47

Update index.md

99d0282

Fixed bugs

c11d1ea

fixed broken link

1a8ac71

fixed broken link

e48ffe1

MichaelHatherly requested changes Sep 20, 2020

View reviewed changes

mortenpi added the Type: Documentation label Sep 20, 2020

haampie reviewed Oct 22, 2020

View reviewed changes

mortenpi closed this Nov 1, 2023


		The [Package Guide](@ref) provides a tutorial explaining how to get started using Documenter.

		A quickstart version of the guide can be found at [Quickstart]("https://github.com/JuliaDocs/Documenter.jl/blob/master/docs/src/quickstart.md")


		See the [Index](@ref main-index) for the complete list of documented functions and types.

	5. Now in the docs folder make this heirarchy
	5. Now in the docs folder make this hierarchy

Quick start :) #1419

Quick start :) #1419

Uh oh!

Conversation

SubhadityaMukherjee commented Sep 20, 2020

Uh oh!

MichaelHatherly left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MichaelHatherly commented Sep 20, 2020

Uh oh!

mortenpi commented Sep 27, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

knuesel commented Jan 24, 2021

Uh oh!

mortenpi commented Nov 1, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants