New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Tutorial screenshot appears to be out of date. #870

Closed
lanceleonard opened this Issue Mar 18, 2016 · 3 comments

Comments

Projects
None yet
3 participants
@lanceleonard

lanceleonard commented Mar 18, 2016

When working through the tutorial, ("Getting Started" section) the screen shot displaying the default index page is incorrect (presumably out of date). (See on mkdocs, version 0.15.3, OS X and Windows.)

To reproduce:

  1. Create a new project as instructed in the first step of the tutorial.
  2. Change to the directory created for the new project.
  3. Run the serve command.
  4. Open your browser to http://127.0.0.1:8000 and note that the default index page is different than what's presented in the screenshot.

(Also, the sentence "Once you hit reload in the browser you'll see your new site name take effect." contains a typo. It should be "Once you hit reload in the browser, you'll see your new site name take effect." Rewriting the sentence to something along the lines of "Reload the page in your browser to see the new site name." may be even better.)

@waylan

This comment has been minimized.

Member

waylan commented Mar 18, 2016

Interesting observation. The screenshots show example pages filled with Lorem ipsum filler text (well, actually "lorem markdownum"; presumably someones attempt at being cute 👎 ). However, the actual text displayed at that point in the tutorial is not that text. but a single line header: "Welcome to MkDocs" (see mkdocs/commands/new.py#L9).

The real question is: what should we change, the screenshots or the default text? The screenshots are definitely more attractive as they are today (they better demonstrate what pages could look like), but the the actual pages leave less for the user to replace/delete when they add some real content.

@waylan

This comment has been minimized.

Member

waylan commented Mar 18, 2016

I also notice that a second page is already present in the first screenshot, but adding a second page isn't covered until later in the tutorial (with no screenshot provided at that point). Seems to me like the tutorial needs a little work in general.

@d0ugal

This comment has been minimized.

Member

d0ugal commented Mar 18, 2016

Seems to me like the tutorial needs a little work in general

+1

waylan added a commit to waylan/mkdocs that referenced this issue Apr 2, 2016

Updated Documentation Home Page/Tutorial.
* Updated screenshots to reflect the actual pages in the tutorial (fixes mkdocs#870).
* Added a few new screenshots to demonstrate more features (search).
* Replaced the `initial-config.png` screenshot with a code block.
* Corrected the inconsistant use of "you" and "we" throughout (use "you").
* Added links to various locations in the docs where appropriate.
* General cleanup, formatting, etc.

@waylan waylan closed this in #882 Apr 3, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment