Improve the getting started docs #4676

davidfischer · 2018-09-28T22:55:34Z

Adds an introductory few paragraphs to docs/index page to explain the value proposition of Read the Docs. The goal here is to answer the "Why Read the Docs" question.
Breaks the getting started guide into 3 docs
- getting started with Sphinx
- getting started with MkDocs (this is brand new)
- importing your documentation
In the getting started with X guides, I briefly explain the benefits/trade-offs of using Sphinx/MkDocs
Puts "connecting your account" (to GitHub, Bitbucket, GitLab) into a separate doc rather than in the getting started guide. This won't be as necessary going forward as more people choose to sign up with GitHub, etc.
In the toctree, moves:
- the "about Read the Docs" section below "Feature documentation"
- puts the "Design" section into the developer documentation

After merging

Create a redirect in the Read the Docs project dashboard for the "docs" project from getting-started.html -> intro/getting-started-with-sphinx.html.

Notes

I would like to put full sentence/paragraph descriptions on different sections (eg. User documentation, Feature documentation, About Read the Docs, etc.), but there isn't a great way to do this. I still think we should do it to explain the differences between those various sections. Currently the best path I have for that is similar to what I did with "First steps" which is to make the toctree hidden and then also have duplicate links to the documents.

What are peoples' thoughts on having more screenshots in our docs? I put one in the import guide but I could easily create a lot more. I think especially in getting started guides, these are very reassuring and show people they are doing the right thing in the right place.

Fixes #4648

stsewd

I like these new docs! Shouldn't we mention the configuration part here? Like using a configuration file or the web admin.

stsewd · 2018-09-28T23:07:14Z

docs/intro/getting-started-with-mkdocs.rst

+
+.. sourcecode:: bash
+
+    $ pip install mkdocs


I'm not sure how this is rendered, but maybe dropping the $ makes easier to copy/paste

It doesn't really render any different from the existing getting started guide. The only difference is that any shell builtins (eg. echo, cd, etc.) are syntax highlighted. It also is more explicit.

There's a few places in our docs that use the pattern of $ shellcommand so I'm hesitant to change it without changing it everywhere.

I generally dislike the $ for the reason mentioned (hard to copy/paste), but don't feel strongly.

I added an issue for it: #4698

stsewd · 2018-09-28T23:09:32Z

docs/intro/getting-started-with-mkdocs.rst

+Open up http://127.0.0.1:8000/ in your web browser to see your documentation.
+You can make changes to your Markdown files and your docs will automatically rebuild.
+
+Once you have your documentation in a public repository such GitHub, Bitbucket, or GitLab,


I'm not an English guy, but shouldn't be such as?

Yes it should. Thanks

stsewd · 2018-09-28T23:12:03Z

docs/intro/getting-started-with-sphinx.rst

+.. sourcecode:: bash
+
+    $ cd /path/to/project
+    $ mkdir docs


We don't mention this on the MkDocs guide

Correct. Running mkdocs new . creates mkdocs.yml at the root (not in docs/) and docs/index.md.

It also creates the docs directory if it doesn't exist.

stsewd · 2018-09-28T23:13:22Z

docs/intro/getting-started-with-sphinx.rst

+
+.. sourcecode:: bash
+
+    $ make html


Maybe mentioning that this is only valid for unix like systems?

For Windows, I believe it works as-is because Sphinx will create a make.bat file.

davidfischer · 2018-09-28T23:30:54Z

Shouldn't we mention the configuration part here? Like using a configuration file or the web admin.

I think that's a great idea.

Where do you think it should go? Perhaps just a sentence or two in "Importing Your Documentation >> Building your documentation" and it links to the Yaml config docs?

I also think the Yaml config docs should be linked from the builds docs.

stsewd · 2018-09-28T23:36:37Z

I also think the Yaml config docs should be linked from the builds docs.

Definitely, that's a good place

Where do you think it should go? Perhaps just a sentence or two in "Importing Your Documentation >> Building your documentation" and it links to the Yaml config docs?

That's a good question p: not sure, maybe it makes sense on an early step? Looks like an intermediate step between creating the documentation and importing/building it on rtd.

davidfischer · 2018-09-28T23:38:29Z

If you don't have a strong opinion, I lean toward putting it in "Importing Your Documentation >> Building your documentation". I think that because many projects (especially simple ones) won't need it and I want to keep the getting started guide short and simple.

davidfischer · 2018-09-28T23:52:18Z

I linked to the Yaml config on "Importing Your Documentation". The builds page needs a bit more work and is a little out of scope for this PR. I created #4679 to handle it.

ericholscher · 2018-10-01T12:13:02Z

docs/connected-accounts.rst

+* Log into Read the Docs with your GitHub, Bitbucket, or GitLab credentials
+
+To connect your account, go to your *Settings* dashboard and select *Connected
+Services*. From here, you'll be able to connect to your GitHub, Bitbucket or GitLab


I believe you can also just "login" with the accounts and it will connect them. This is probably the most explicit way of documenting doing it though 👍

Signing up will connect them. I'll make that a bit more clear.

ericholscher · 2018-10-01T12:14:21Z

docs/intro/getting-started-with-mkdocs.rst

+
+.. sourcecode:: bash
+
+    $ pip install mkdocs


I generally dislike the $ for the reason mentioned (hard to copy/paste), but don't feel strongly.

ericholscher

Looks great.

What are peoples' thoughts on having more screenshots in our docs? I put one in the import guide but I could easily create a lot more. I think especially in getting started guides, these are very reassuring and show people they are doing the right thing in the right place.

I like screenshots. We don't have a great way of managing them, but I'm +1 on having them, especially in tutorial/intro docs.

ericholscher · 2018-10-01T12:17:23Z

docs/index.rst

@@ -105,6 +124,8 @@ Information about development is also available:
   i18n
   issue-labels
   security
+   design
+   RTD Theme <https://sphinx-rtd-theme.readthedocs.io/en/latest/>


We should really make this a subproject and have a nicer integration between the two sets of docs.

Can you go into a little more detail about what you mean by this?

We should make it a subproject and use some of our fancier features that we build for users on our own stuff.

i started on this path to restructure all of our docs -- add all subprojects/translations and break up community user docs, community developer docs, and commercial docs. probably part of a larger thing that we should dog food on the .com

davidfischer · 2018-10-01T21:46:01Z

I like screenshots. We don't have a great way of managing them, but I'm +1 on having them, especially in tutorial/intro docs.

I added screenshots. I moved the images around (under _static) and re-enabled html_static_path so that I could create hyperlinks to the images themselves.

davidfischer · 2018-10-01T21:46:54Z

The lint errors are due to search stuff, not these docs.

agjohnson

Content looks great, just noted a couple small changes that aren't super important.

A larger issue is that content here does not reflect our commercial hosting, but we don't have a good pattern for this yet anyways. We'll need to revisit this to make the necessary changes there (no manual import, you must be repo admin to import, etc, etc)

docs/intro/getting-started-with-mkdocs.rst

agjohnson · 2018-10-02T18:32:53Z

docs/intro/getting-started-with-sphinx.rst

+    and many projects large and small use Sphinx
+    including the Django project and the Python programming language.
+    However, Read the Docs also supports :doc:`MkDocs </intro/getting-started-with-mkdocs>`,
+    another tool for writing and building documentation.


I don't think we necessarily want to point out mkdocs here, if anything because we're not giving a reason for the user to consider mkdocs with this sentence. I think our position is that the author would be better off with Sphinx and RTD anyways, due to the lack of feature parity on mkdocs. I'd be 👍 on dropping the mkdocs callout here.

I removed it. We could also discuss some of the differences like lack of PDF/e-reader support in mkdocs but I don't know if it is necessary.

Good point, yeah. Perhaps a good doc to have in general, but i'd agree, not necessary for getting started PR here.

…ents

Improve the getting started docs

4adc1f5

davidfischer requested a review from a team September 28, 2018 22:55

davidfischer mentioned this pull request Sep 28, 2018

Fix broken docs links #4677

Merged

stsewd reviewed Sep 28, 2018

View reviewed changes

Fix a typo

7a1beca

Link to the yaml config from the import guide

e0b7ef1

davidfischer mentioned this pull request Sep 28, 2018

Improve the Build Process Documentation #4679

Closed

ericholscher reviewed Oct 1, 2018

View reviewed changes

ericholscher approved these changes Oct 1, 2018

View reviewed changes

readthedocs deleted a comment from 7mobile56 Oct 1, 2018

davidfischer mentioned this pull request Oct 1, 2018

Remove $ before shell commands in docs #4698

Closed

davidfischer added 2 commits October 1, 2018 14:01

Improve connected accounts docs

ee7aa3c

Add screenshots to getting started docs

b348c04

agjohnson reviewed Oct 2, 2018

View reviewed changes

davidfischer added 2 commits October 2, 2018 16:41

Merge branch 'master' into davidfischer/docs-getting-started-improvem…

176c3ca

…ents

Remove link to MkDocs from Sphinx getting started guide

66ea0f3

davidfischer merged commit d3d922d into master Oct 5, 2018

davidfischer deleted the davidfischer/docs-getting-started-improvements branch October 5, 2018 18:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve the getting started docs #4676

Improve the getting started docs #4676

davidfischer commented Sep 28, 2018

stsewd left a comment

stsewd Sep 28, 2018

davidfischer Sep 28, 2018

ericholscher Oct 1, 2018

davidfischer Oct 1, 2018

stsewd Sep 28, 2018

davidfischer Sep 28, 2018

stsewd Sep 28, 2018

davidfischer Sep 28, 2018 •

edited

Loading

davidfischer Sep 28, 2018

stsewd Sep 28, 2018

davidfischer Sep 28, 2018

davidfischer commented Sep 28, 2018

stsewd commented Sep 28, 2018

davidfischer commented Sep 28, 2018

davidfischer commented Sep 28, 2018

ericholscher Oct 1, 2018

davidfischer Oct 1, 2018

ericholscher Oct 1, 2018

ericholscher left a comment

ericholscher Oct 1, 2018

davidfischer Oct 1, 2018

ericholscher Oct 2, 2018

agjohnson Oct 2, 2018

davidfischer commented Oct 1, 2018

davidfischer commented Oct 1, 2018

agjohnson left a comment

agjohnson Oct 2, 2018

davidfischer Oct 2, 2018

agjohnson Oct 3, 2018

Improve the getting started docs #4676

Improve the getting started docs #4676

Conversation

davidfischer commented Sep 28, 2018

After merging

Notes

stsewd left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidfischer Sep 28, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidfischer commented Sep 28, 2018

stsewd commented Sep 28, 2018

davidfischer commented Sep 28, 2018

davidfischer commented Sep 28, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidfischer commented Oct 1, 2018

davidfischer commented Oct 1, 2018

agjohnson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidfischer Sep 28, 2018 •

edited

Loading