Dvc.org: user-guide: rename user-manual?

[jorgeorpinel]

• [ ] Rename User Guide section to User Manual? Better naming because we can call each document inside a "guide" without causing confusion with the parent section (the manual).

• [x] And update the guide title "Update Tracked Files" to "Updating".

Would also need to setup a (tmp) redirect in server.js, update the GitHub label, et al.

[shcheklein]

@jorgeorpinel up to you :) but, I don't see a strong reason to do so. What sections do you want to call "guide" inside?

[jorgeorpinel]

Yeah, not a huge deal, not sure it's worth the trouble but I do think it would be an improvement.

What sections do you want to call "guide" inside?

All the documents inside would be the "guides" (implicitly or explicitly). The ones listed in https://dvc.org/doc/user-guide.

[shcheklein]

@jorgeorpinel if all of them are "guides" in an implicit sense, then it's correct to have a "User Guide" name. I think it's better to not repeat Guide multiple times inside.

[jorgeorpinel]

We don't really have to call them "guides". In fact we don't often do. But if we're going to, at least call the parent section "User Guides"? (plural).

But I don't think this section is much of a "guide". Guiding information doesn't go into detail, just uses the most convenient steps to get from A to B. I think the Get Started section could be seen as a guide, but the stuff here is some of the most technical in our docs, more like a reference manual.

The usage of the term "guide" should definitely be reviewed though. We don't have much consistency there. I'll take a look...

[shcheklein]

I think "* Guide" is a pretty established naming in tech docs. Check HBase docs, look for Administrator Guide, Programmer's Guide, etc. All of them consist internally out of other smaller "guides". Also - https://en.wikipedia.org/wiki/User_guide

[jorgeorpinel]

Good arguments. But still I'm not convinced.

From the Wikipedia article: "User manuals and user guides ... are book-like documents with contents similar to the above list." (cover page, copyright, preface, ToC, Purpose, Audience, Scope sections...) From this description, HBase's Reference Guide is a user guide/manual, but our User Guide section is neither. It also reads "The term guide is often applied to a document that addresses a specific aspect of a software product. Some usages are _Installation_ Guide, _Getting Started_ Guide, and various _How to_ guides."

I think "* Guide" is a pretty established naming in tech docs.

You're right, AWS uses the term for example. But I can't really find many other examples so not sure how well established it is. (Most projects don't seem to use either term.)

I think it's up to us. I would try to avoid using an unconvincing term just because others do so, but at the same time, as discussed, this is not a very impactful change.

However, as long as we use the title User Guide, we may need to be careful about the term "guide" in general (for example not calling the Get Started a guide, since it's not part of the User Guide), which is one of the motivations for my suggestion in this issue. (See for example this change which wouldn't be needed with User Manual: https://github.com/iterative/dvc.org/pull/710/commits/4a9e57b97e961d425bd9f0d233cb9eadacf2aa30)

[jorgeorpinel]

update the guide title "Update Tracked Files" to "Updating"

BTW I did this in https://github.com/iterative/dvc.org/pull/725/commits/dbcefaf0ff122f8c0f6fdfaf08e40725431fcda7.

[shcheklein]

another good example of the user guide with an explanation what User Guide is about:

https://dev.pandas.io/docs/user_guide/index.html

also, might be a good example of the getting started section - may be we can make structure our get started into isntallation (move it back from the top level), quick intro (create a separate level for the current content), move tutorials inside from the top level. cc @dashohoxha

[dashohoxha]

I have no strong opinion on the issue of User Guide vs. User Manual. When I hear "manual" I am reminded of man pages on Unix/Linux (I am not sure whether Mac and Windows have something similar). So, in my opinion, User Manual might be an alternative to Command Reference, not to User Guide.
Anyway, I am in favor of keeping things as they are, unless there is a good reason for changing them.

About the Pandas doc site, it doesn't seem to me a professional or an exceptionally good one. I might even say that on the first sight (without going to much details) it seems an ordinary one and even a bit messy. So I don't know why we should take that one as an example. A blind following another blind so that he doesn't get lost? Or just we are not able to think of a reasonable structure for our docs?

Anyway, I think it is a good idea to discuss about the structure of the docs and reach some conclusions, instead of making small random changes here and there and hoping that these will make the docs better. I think that we should have a plan about how we would like to improve the docs.

[jorgeorpinel]

I guess this one is unnecessary.